Introduction 


This book is about two software packages called Tcl and Tk Tel is a 
dynamic language (also known as a scripting language) for controlling 
and extending applications; its name stands for “tool command language.” 
Tcl provides general programming facilities sufficient for most applications. 
Furthermore, Tcl is both embeddable and extensible. Its interpreter is a 
library of C functions that can easily be incorporated into applications, and 
each application can extend the core Tcl features with additional commands 
either unique to the application or provided by add-on libraries (referred to 
as extensions 1n the Tcl community). 


1. The official pronunciation for Tcl 1s “tickle,” although “tee-see-ell” is 
also used frequently. Tk 1s pronounced “‘tee-kay.” 


One of the most useful extensions to Tcl is Tk, which is a toolkit for 
developing graphical user interface (GUI) applications. Tk extends the core 
Tcl facilities with commands for building user interfaces, so that you can 
construct GUIs by writing Tcl scripts instead of C code. Like Tcl, Tk is 
implemented as a library of C functions so it can be used in many different 
applications. 


Note 


This book corresponds to Tcl/Tk version 8.5. The release notes for 
each version of Tcl/Tk describe the changes and new features in each 
release. The Tcler’s Wiki web site (nttp://wiki.tci.tk) also compiles 
change lists for each release; you can find them by searching for pages 
that contain Changes in in the title. 


I.1 Benefits of Tel/Tk 


Together, Tcl and Tk provide several benefits to application developers and 
users. The first benefit is rapid development. Many interesting applications 
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can be written entirely as Tcl scripts. This allows you to program at a much 
higher level than you would in C/C++ or Java, and Tk hides many of the 
details that C or Java programmers must address. Compared to low-level 
toolkits, there is much less to learn in order to use Tcl and Tk, and much less 
code to write. New Tcl/Tk users often can create interesting user interfaces 
after just a few hours of learning, and many people have reported tenfold 
reductions in code size and development time when they switched from 
other toolkits to Tcl and Tk. 

Another reason for rapid development with Tcl and Tk is that Tcl is an 
interpreted language. When you use a Tcl application, you can generate and 
execute new scripts on the fly without recompiling or restarting the 
application. This allows you to test out new ideas and fix bugs rapidly. 
Since Tcl is interpreted, it executes more slowly than compiled C code; but 
internal optimizations, such as bytecode compilation coupled with ever- 
increasing processor power, have erased most of the perceived performance 
advantages of compiled languages. For example, you can execute scripts 
with hundreds of Tcl commands on each movement of the mouse with no 
perceptible delay. In the rare cases where performance becomes an issue, 
you can reimplement the performance-critical parts of your Tcl scripts in C. 
A second benefit is that Tcl is a cross-platform language, as are most of its 
extensions, including Tk. This means that an application developed on one 
platform, such as Linux, in most cases can be run without change on another 
platform, such as Macintosh or Windows. 

Tcl was also the first dynamic language to have native Unicode support. As 
a result, Tcl applications can handle text in virtually any of the world’s 
written languages. Tcl requires no extensions to process text in any of the 
Unicode-supported scripts, and standard extensions such as msgcat provide 
simple localization support. 

Another significant benefit is that Tcl and most of its extensions are freely 
available as open source. Tcl and Tk follow the so-called BSD license, 
which allows anyone to download, inspect, modify, and redistribute Tcl/Tk 
without charge. 

Tcl is an excellent “glue language.” A Tcl application can include many 
different extensions, each of which provides an interesting set of Tcl 
commands. Tk is one example of a library package; many other packages 
have been developed by the Tcl/Tk community, and you can also write your 
own packages. Tcl scripts for such applications can include commands from 
any of the packages. 

Additionally, Tcl makes it easy for applications to have powerful scripting 
languages. For example, to add scripting capability to an existing 
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application, all you need do is implement a few new Tcl commands that 
provide the basic features of the application. Then you can link your new 
commands with the Tcl library to produce a full-function scripting language 
that includes both the commands provided by Tel (called the 7c/ core) and 
those that you wrote. 

Tcl also provides user convenience. Once you learn Tcl and Tk, you will be 
able to write scripts for any Tcl and Tk application merely by learning the 
few application-specific commands for the new application. This should 
make it possible for more users to personalize and enhance their 
applications. 


1.2 Organization of the Book 


Chapter_1 uses several simple scripts to provide a quick overview of the 
most important features of Tcl and Tk. It 1s intended to give you the flavor of 
the systems and convince you that they are useful, without explaining 
anything in detail. The remainder of the book goes through everything again 
in a more comprehensive fashion. It is divided into three parts: 
¢ Part I introduces the Tcl scripting language. After reading this 
section, you will be able to write scripts for Tcl applications. You 
will need to know at least some of the information in this part in 
order to write Tk applications. 
¢ Part II describes the additional Tcl commands provided by Tk, 
which allow you to create user-interface widgets such as menus and 
scrollbars and arrange them in GUI applications. After reading this 
section, you will be able to create new GUI applications and write 
scripts to enhance existing Tk applications. 
¢ Part III discusses the C functions in the Tcl library and how to use 
them to create new Tcl commands. After reading this section, you 
will be able to write new Tcl packages and applications in C. 
However, you will be able to do a great deal (perhaps everything 
you need) without this information. 
Each of these parts contains about a dozen short chapters. Each chapter is 
intended to be a self-contained description of a piece of the system, and you 
need not necessarily read the chapters in order. 
Not every feature of Tcl and Tk is covered here, and the explanations are 
organized to provide a smooth introduction rather than a complete reference 
source. A separate set of reference manual entries, referred to as the 
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reference documentation, is available with the Tcl and Tk distributions. 
These are much more terse but they cover absolutely every feature of both 
systems. Appendix A describes how to retrieve the Tcl and Tk distributions, 
including reference documentation, via the Internet. Appendix B provides a 
survey of some popular Tcl extensions. Appendix C lists additional online 
and printed resources for Tcl and Tk. The full Tcl Source Distribution 
License is included in Appendix D. 

This book assumes that you already know how to use your operating system, 
including interacting with applications from the command line. Part II of 
this book assumes that you are familiar with the C programming language as 
defined by the ANSI C standard; a basic knowledge of C is helpful for Parts 
I and II but not required. You need not know anything about either Tcl or Tk 
before reading this book; both are introduced from scratch. 


1.3 Notation 


This book uses a monospace font for anything that might be typed to a computer, 
such as Tcl scripts, C code, and names of variables, procedures, and 
commands. The examples of Tcl scripts use notation like the following: 


set a 44 
=>44 


Tcl commands, such as set a 44 in the example, appear 1M monospace; their 
results, such as 44 in the example, appear in italicized monospace. The > 
symbol before the result indicates that this is a normal return value. If an 
error occurs in a Tcl command, the error message appears in italicized 
monospace, preceded by a © symbol to indicate that this is an error rather than 
a normal return: 


set a 44 55 
© wrong #args: should be "set varName ?newValue?" 


When describing the syntax of Tcl commands, italicized Courier is used for 
formal argument names. An argument or group of arguments enclosed in 
question marks indicates that the arguments are optional. For example, the 
syntax of the set command is as follows: 


set varName ?newValue? 
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This means that the word set must be entered verbatim to invoke the 
command, and varwame and newvaiue are the names of set’s arguments; when 
invoking the command, you type a variable name instead of varname and a 
new value for the variable instead of newvaiue. The newvaiue argument is 
optional. 
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1. An Overview of Tcl and Tk 


This chapter introduces Tcl and Tk with a series of scripts illustrating their 
main features. Although you should be able to start writing simple scripts 
after reading this chapter, the explanations here are not complete. The 
purpose of this chapter is to show you the overall structure of Tcl and Tk 
and the kinds of things they can do, so that when individual features are 
discussed in detail you'll be able to see why they are useful. All of the 
information in this chapter 1s revisited in more detail in later chapters, and 
several important aspects, such as the Tcl C interfaces, are not discussed at 
all in this chapter. 


1.1 Getting Started 


To invoke Tcl scripts, you must run a Tcl application. If Tcl is installed on 
your system, there should exist a simple Tcl shell application called tcisn, 
which you can use to try out some of the examples in this chapter. If Tcl has 
not been installed on your system, refer to Appendix A for information on 
how to obtain and install it. 


Note 


It’s common practice to install ¢cisn with its version number as part of 
the name (for example, tcishs.s on Unix or tcisnss on Windows). This 
has the advantage of allowing multiple versions of Tcl to exist on the 
same system at once, but also the disadvantage of making it harder to 
write scripts that start uniformly across different versions of Tcl. 
Therefore, most installers also commonly link or alias tcisn to the most 
recent version installed on the system. The same is true for the wisn 
interpreter, described later. Therefore, unless you want to use a 
specific version of a Tcl application installed on your system, you 
should simply use tcish OF wish. 


You can start the tcisn application by opening a terminal window on a 
Macintosh or Unix system, or a command prompt window on a Windows 
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system, and then entering the command 
tclsh 


This causes tcisn to start in interactive mode, reading Tcl commands from 
the keyboard and passing them to the Tcl interpreter for evaluation. For 
starters, enter the following command at the tcisn prompt: 


expr 2 + 2 


tclsh prints the result (4) and then prompts you for another command. 

This example illustrates several features of Tcl. Each command consists of 
one or more words separated by spaces or tabs (referred to as whitespace 
characters). In the example there are four words: expr, 2, +, and 2. The first 
word of each command is the name of the command to execute. The other 
words are arguments that are passed to the command for processing. expr 1S 
one of the core commands provided by the Tel library, so it exists in every 
Tcl application. It concatenates its arguments into a single string and 
evaluates the string as an arithmetic expression. 

Each Tcl command returns a result. If a command has no meaningful result, 
it returns an empty string. For the expr command the result is the value of the 
expression. 

All values in Tcl have a string representation and may also have a more 
efficient internal representation. In this example, expr’s result is a numerical 
value that would have a binary integer or floating-point internal 
representation. The internal representation allows faster and more efficient 
processing of information. If the value simply is assigned to a variable or if 
it is used by another command expecting a numerical value, this is done 
very efficiently as no string conversion is required. Tcl automatically 
generates a string representation of a value on an as-needed basis—for 
example, when the value is displayed on the console. 


Note 


At the script development level, you can treat all values as strings; Tcl 
converts between the string and the internal representation 
automatically as needed. As you grow more familiar with Tcl, 
understanding what can cause conversions can help you avoid them, 
resulting in more efficient and faster code. In general, always being 
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consistent in your treatment of a value (e.g. always using list 
commands to process lists, always using dictionary commands to 
process dictionaries, etc.) and avoiding unnecessary printing and other 
string manipulation of numeric, list, and dictionary values can go a 
long way in speeding up your code. For more information on the 
internal representation of values at the C language level, see Chapter 
32. 


From now on, we will use notation such as the following to describe 
examples: 


expr 2 +2 
> 4 


The first line 1s the command you enter and the second line 1s the result 
returned by the command. The > symbol indicates that the line contains a 
return value; the = is not actually printed out by tcish. We will omit return 
values in cases where they aren’t important, such as sequences of commands 
where only the last command’s result matters. 
Commands are normally terminated by newlines (typically the Enter or 
Return key on your keyboard), so each line that you enter in tcisn normally 
becomes a separate command. Semicolons also act as command separators, 
in case you wish to enter multiple commands on a single line. It is also 
possible for a single command to span multiple lines; you'll see how to do 
this later. 
The expr command supports an expression syntax similar to that of 
expressions in ANSI C, including the same precedence rules and most of the 
C operators. Here are a few examples that you could enter in tcisn: 
expr 2 * 10 - 1 
=» 19 
expr 14.1*6 
=> 84.6 
expr sin(.2) 
=> 0.19866933079506122 
expr rand() 
= 0.62130973004797 
expr rand() 
=> 0.35263291623100307 
expr (3 > 4) | (6 <= 7) 


> 2 


The first example shows the multiplication operator and how it has a higher 
precedence than subtraction. The second shows that expressions can contain 
real values as well as integer values. The next examples show some of the 
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built-in functions supported by expr, including the ranai) function for 
generating random numbers between 0 and |. The last example shows the 
use of the relational operators > and <- and the logical OR operator |;. As in 
C, Boolean results are represented numerically with i for true and o for 
false. 

To leave tcisn, invoke the exit command: 


exit 


This command terminates the application and returns you to your shell. 


1.2 “Hello, World!” with Tk 


Tel provides a full set of programming features such as variables, loops, 
and procedures. It can be used by itself or with extensions that implement 
their own Tcl commands in addition to those in the Tcl core. 

One of the more interesting extensions to Tcl is the set of windowing 
commands provided by the Tk toolkit. Tk’s commands allow you to create 
graphical user interfaces. Many of the examples in this book use an 
application called wisn (“windowing shell’), which is similar to tcisn except 
that it also includes the commands defined by Tk. If Tcl and Tk have been 
installed on your system, you can invoke wisn from your terminal or 
command prompt window just as you did for tcisn; it displays a small empty 
window on your screen and then reads commands from the console. 
Alternatively, if you have Tcl/Tk version 8.4 or later installed, you can 
invoke the tcisn application, and then use the command package require tk to 
dynamically load the Tk extension. 


Note 


On Windows, invoking an interactive wisn session displays both the 
empty window and a separate console window. The console window 
is a replacement for a real console to allow input and output on the 
standard I/O channels. The console window normally is hidden when a 
script file is executing, as described later, although you can display it 
by executing the console show Command. Consult the conscie reference 
documentation for more information. 
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Here is a simple Tk script that you could run with wisn: 


button .b -text "Hello, world!" -command exit 
grid .b 


If you enter these two Tcl commands in wisn, the window’s appearance 
changes to that shown in Figure 1.1. If you move the pointer over the “Hello, 
world!” text and click the main mouse button (the leftmost button in most 
configurations), the window disappears and wisn exits. 


Figure 1.1 The “Hello, world!” application 


Hello, world! | 


Several things about this example need explanation. First let us deal with 
the syntactic issues. The example contains two commands, putton and gria, 
both of which are implemented by Tk. Although these commands do not look 
like the expr command in the previous section, they have the same basic 
structure as all Tcl commands: one or more words separated by whitespace 
characters. The button command contains six words, and the gria command 
contains two words. 

The fourth word of the nutton command is enclosed in double quotes. This 
allows the word to include whitespace characters; without the quotes, se11o, 
and woria!: would be separate words. The double quotes are delimiters, not 
part of the word itself; they are removed by the Tcl interpreter before the 
command is executed. 

For the expr command the word structure doesn’t matter much since expr 
concatenates all its arguments. However, for the button and gria commands, 
and for most Tcl commands, the word structure is important. The button 
command expects its first argument to be the name of a new window to 
create. Additional arguments to this command must come in pairs, where the 
first argument of each pair is the name of a configuration option and the 
second argument is a value for that option. Thus if the double quotes were 
omitted, the value of the -text option would be seiic, and woria: would be 
treated as the name of a separate configuration option. Since there is no 
option defined with the name wor1a: the command would return an error. 
Now let us move on to the behavior of the commands. The basic building 
block for a graphical user interface in Tk is a widget. A widget is a window 
with a particular appearance and behavior (the terms widget and window 
are used synonymously in Tk). Widgets are divided into classes such as 
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buttons, menus, and scrollbars. All the widgets in the same class have the 
same general appearance and behavior. For example, all button widgets 
display a text string, bitmap, or image and execute a Tcl script when the user 
clicks the button. 
Widgets are organized hierarchically in Tk, with names that reflect their 
positions in the hierarchy. The main widget, which appeared on the screen 
when you started wisn, has the name . and .» refers to a child » of the main 
widget. Widget names in Tk are like file name paths except that they use . as 
a separator character instead of / or \. Thus, .a.».c refers to a widget that is 
a child of widget .a.», which in turn is a child of .2, which is a child of the 
main widget. 
Tk provides one command for each class of widgets, called a class 
command, which you invoke to create widgets of that class. For example, 
the button command creates button widgets. This is similar to standard 
object-oriented programming principles, though Tk doesn’t support direct 
subclassing of the widget classes. All of the class commands have the same 
form: the first argument is the name of a new widget to create, and 
additional arguments specify configuration options. Different widget classes 
support different sets of options. Widgets typically have many options, with 
default values for the options that you don’t specify. When a class command 
like button 18 invoked, it creates a new widget with the given name and 
configures it as specified by the options. 
The button command in the example specifies two options: -text, which is a 
string to display in the button, and -commana, which is a Tel script to execute 
when the user invokes the button. In this example the -commana Option 1S exit. 
Here are a few other button options that you can experiment with: 

® -pbackgrouna—the background color for the button, such as biue 

® -foregrouna—the color of the text in the button, such as piack 

* -font—the font to use for the button, such as "times 12" for a 12-point 

Times Roman font 

Creating a widget does not automatically cause it to be displayed. The gria 
command causes the button widget to appear on the screen. Independent 
entities called geometry managers are responsible for computing the sizes 
and locations of widgets and making them appear on the screen. The 
separation of widget creation and geometry management provides 
significant flexibility in arranging widgets on the screen to design your 
application. The gria command in the example asks a geometry manager 
called the gridder to manage .». The gridder arranges widgets in a grid of 
columns and rows. In this case, the command placed .» in the first column of 
the first row of the grid and sized the grid to just large enough to 
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accommodate the widget; furthermore, if the parent has more space than 
needed by the grid, as in the example, the parent is shrunk so that it is just 
large enough to hold the child. Thus, when you entered the gria command, 
the main window (.) shrank from its original size to the size that appears in 


Figure 1.1. 


1.3 Script Files 


In the examples so far, you have entered Tcl commands interactively to tcisn 
Or wish. You can also place commands into script files and invoke the script 
files just like shell scripts. To do this for the “Hello, world!” example, 
place the following text in a file named ne1to.tc1! 


#!/usr/local/bin/wish 
button .b -text "Hello, world!" -command exit 
pack .b 


You can execute this script by invoking the wisn interpreter and passing the 
script file name as a command-line argument: 


wish hello.tcl 


This causes wisn to display the same window as shown in Figure 1.1 and 
wait for you to interact with it. In this case you will not be able to type 
commands interactively to wisn; all you can do 1s click on the button. 


1.3.1 Executable Scripts on Unix and Mac OS X 


The script just shown is the same as the one you typed earlier except for the 
first line. As far as wish 18 concerned, this line is a comment, but on Unix 
systems if you make the file executable (for example, by executing chmoa +x 
hello.te1 In your shell), you can then invoke the file directly by typing 
hello.tc1 to your shell. (This requires the directory containing your heito.tc1 
script to be listed in your ears environment variable.) When you do this, the 
system invokes wisn, passing it the file as a script to interpret. 

As written, this script works as an executable script only if wisn is installed 
IN /usr/local/bin, although you could still run it by invoking wisn with the 
script file name as a command-line argument. If wish has been installed 
somewhere else, you need to change the first line to reflect its location on 
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your system. Some systems misbehave in confusing ways if the first line of 
the script file is longer than 32 characters, so beware if the full path name of 
the wisn binary is longer than 27 characters. 

To work around these limitations, a common technique for scripts on Unix 
has been to start script files with the following three lines: 


#!/bin/sh 
# Tcl ignores the next line but 'sh' doesn't \ 
exec wish "$0" "S@" 


or the more arcane but more robust version: 


#!/bin/sh 
# Tcl ignores the next line but 'sh' doesn't \ 
exec wish "SO" ${1+"$e"} 


In most modern Unix implementations, though, the following will work 
correctly, as long as wisn appears in one of the directories in your pata 
environment variable: 


#!/usr/bin/env wish 


1.3.2 Executable Scripts on Windows 


On Windows, you can use the standard system tools to associate the wisn 
interpreter with a file extension (.tc1 by convention) so that double-clicking 
on the icon for a Tcl/Tk script automatically invokes the wish interpreter, 
passing it the name of the file as a script to interpret. Most Windows 
installers for Tcl/Tk automatically create this association for you. wish is 
typically selected as the default association because most Windows-based 
Tcl/Tk programs are GUlI-based. However, if the majority of your Tcl 
scripts don’t use Tk commands, you could change the default association to 
invoke ¢cisn. 

If you plan to distribute your scripts on multiple platforms, you should 
include the appropriate +: header as discussed in the previous section for 
Unix executable scripts so that they can be directly executable on Unix 
systems. On the other hand, Windows doesn’t follow the +: convention, and 
the +: line is treated as a comment by the wisn interpreter, so the net effect is 
that the line is ignored when the script is run on a Windows system. 


1.3.3 Executing Scripts in an Interactive Interpreter 
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In practice, users of Tk applications rarely type Tcl commands; they interact 
with the applications using the mouse and keyboard in the usual ways you 
would expect for graphical applications. Tcl works behind the scenes where 
users don’t normally see it. The neiio.tci script behaves just the same as an 
application that has been coded in C with a GUI toolkit and compiled into a 
binary executable file. 

During debugging, though, it is common for application developers to type 
Tcl commands interactively. For example, you could test the neiio.tci script 
by starting wisn interactively (type wisn to your shell instead of neiio.tc1). 
Then enter the following Tcl command: 


source hello.tcl 


source 18 a Tcl command that takes a file name as an argument. It reads the 
file and evaluates it as a Tcl script. This generates the same user interface as 
if you had invoked neiio.tci directly from your shell, but you can now enter 
Tcl commands interactively, too. For example, you could edit the script file 
to change the -commana option to 


-command "puts Good-bye!; exit" 


then enter the following commands interactively to wisn without restarting the 
program: 


destroy .b 
source hello.tcl 


The first command deletes the existing button, and the second command re- 
creates the button with the new -commana option. Now when you click on the 
button, the puts command prints a message on standard output before wisn 
exits. 


1.4 Variables and Substitutions 


Tcl allows you to store values in variables and use those values in 
commands. For example, consider the following script, which you could 
enter in either tcish OF wisn! 


seta 44 
= 44 


oY 


expr $a*4 
=> 176 


The first command assigns the value 44 to the variable « and returns the 
variable’s value. In the second command, the s causes Tcl to perform 
variable substitution: the Tcl interpreter replaces the dollar sign and the 
variable name following it with the value of the variable, so that the actual 
argument received by expr 18 44*4. Variables need not be declared in Tcl; they 
are created automatically when set. Variable values can always be 
represented as strings but may be maintained in a native binary format. 
Strings may contain binary data and may be of any length. Of course, in this 
example an error occurs in expr 1f the value of 2 doesn’t make sense as an 
integer or real number. 

Tcl also provides command substitution, which allows you to use the result 
of one command in an argument to another command: 


set a 44 
set b [expr $a*4] 
=> 176 


Square brackets invoke command substitution: everything inside the 
brackets is evaluated as a separate Tcl script, and the result of that script is 
substituted into the word in place of the bracketed command. In this example 
the second argument of the second set command is 176. 

The final form of substitution in Tcl is backslash substitution, which either 
adds special meaning to a normal character or takes it away from a special 
character, as in the following examples: 


set x \$a 
set newline \n 


The first command sets the variable « to the string sa (the characters \s are 
replaced with a dollar sign and no variable substitution occurs). The second 
command sets the variable newiine to hold a string consisting of the newline 
character (the characters \n are replaced with a newline character). 


1.5 Control Structures 


The next example uses variables and substitutions along with some simple 
control structures to create a Tcl procedure called ¢factoriai, Which computes 
the factorial of a given non-negative integer value: 
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proc factorial {val} { 
set result 1 
while {$val>o} { 
set result [expr Sresult*$val] 
incr val -l 


} 


return Sresult 


} 


If you enter the preceding lines in wish or tcisn, or if you enter them into a file 
and then source the file, a new command tactoriai becomes available. The 
command takes one non-negative integer argument, and its result is the 
factorial of that number: 


factorial 3 
=> 6 
factorial 20 
=> 2432902008176640000 
factorial 0.5 
@ expected integer but got "0.5" 


This example uses one additional piece of Tcl syntax: braces. Braces are 
like double quotes in that they can be placed around a word that contains 
embedded spaces. However, braces are different from double quotes in two 
respects. First, braces nest. The last word of the proc command starts after 
the open brace on the first line and contains everything up to the close brace 
on the last line. The Tcl interpreter removes the outer braces and passes 
everything between them, including several nested pairs of braces, to proc as 
an argument. The second difference between braces and double quotes is 
that no substitutions occur inside braces, whereas they do inside quotes. All 
of the characters between the braces are passed verbatim to proc without any 
special processing. 

The proc command takes three arguments: the name of a procedure, a list of 
argument names separated by whitespace, and the body of the procedure, 
which is a Tcl script. proc enters the procedure name into the Tcl interpreter 
as a new command. Whenever the command is invoked, the body of the 
procedure is evaluated. While the procedure body is executing, it can 
access its arguments as variables: vai holds the first and only argument. 

The body of the factoriai procedure contains three Tcl commands: set, white, 
and return. The wniie command does most of the work of the procedure. It 
takes two arguments, an expression, svai>0, and a body, which is another Tcl 
script. The wniie command evaluates its expression argument and if the result 
is nonzero, it evaluates the body as a Tcl script. It repeats this process over 
and over until eventually the expression evaluates to zero. In the example, 
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the body of the wni1e command multiplies the result by vai and then uses the 
incr command to add the specified integer increment (-1 in this case) to the 
value contained in vai. When vai reaches zero, resuit contains the desired 
factorial. 

The return command causes the procedure to exit with the value of the 
variable resuit as the procedure’s result. If a return command is omitted, the 
return value of a procedure is the result of the last command executed in the 
procedure’s body. In the case of factoria: this would be the result of white, 
which is always an empty string. 

The use of braces in this example is crucial. The single most difficult issue 
in writing Tcl scripts is managing substitutions: making them happen when 
you want them and preventing them when you don’t. The body of the 
procedure must be enclosed in braces because we don’t want variable and 
command substitutions to occur at the time the body is passed to proc as an 
argument; we want the substitutions to occur later, when the body is 
evaluated as a Tcl script. The body of the wniie command is enclosed in 
braces for the same reason: rather than performing the substitutions once, 
while parsing the wni1e command, we want the substitutions to be performed 
over and over, each time the body is evaluated. Braces are also needed in 
the (svai>o} argument to wniie. Without them the value of the variable vai 
would be substituted when the wniie command is parsed; the expression 
would have a constant value and wniie would loop forever. Try replacing 
some of the braces in the example with double quotes to see what happens. 
The examples in this book use a style in which the open brace for an 
argument that is a Tcl script appears at the end of one line, the script follows 
on successive indented lines, and the close brace is on a line by itself after 
the script. Although this makes for readable scripts, Tcl doesn’t require this 
particular syntax. Arguments that are scripts are subject to the same syntax 
rules as any other arguments; in fact, the Tcl interpreter doesn’t even know 
that an argument is a script at the time it parses it. One consequence is that 
the open brace must be on the same line as the preceding portion of the 
command. If the open brace is moved to a line by itself, the newline before 
the open brace terminates the command. 

The variables in a procedure are normally local to that procedure and are 
not visible outside the procedure. In the ¢actoriai1 example the local 
variables include the argument vai as well as the variable resuit. A fresh set 
of local variables is created for each call to a procedure (arguments are 
passed by copying their values), and when a procedure returns, its local 
variables are deleted. Variables named outside any procedure are called 
global variables; they last forever unless explicitly deleted. You'll find out 
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later how a procedure can access global variables and the local variables 
of other active procedures. Additionally, persistent variables can be created 
within specific namespaces to prevent naming conflicts; Chapter 10 
discusses the use of namespaces. 


1.6 On the Tcl Language 


As a programming language, Tcl is defined quite differently from most other 
languages. Most languages have a grammar that defines the entire language. 
For example, consider the following statement in C: 


while (val>0) { 
result *= val; 
val -= 1; 


} 


The grammar for C defines the structure of this statement in terms of a 
reserved word wniie, an expression, and a substatement to execute 
repeatedly until the expression evaluates to zero. The C grammar defines 
both the overall structure of the wniie statement and the internal structure of 
its expression and substatement. 

In Tcl no fixed grammar explains the entire language. Instead, Tcl 1s defined 
by an interpreter that parses single Tcl commands, plus a collection of 
procedures that execute individual commands. The interpreter and its 
substitution rules are fixed, but new commands can be defined at any time 
and existing commands can be replaced. Features such as control flow, 
procedures, and expressions are implemented as commands; they are not 
understood directly by the Tcl interpreter. For example, consider the Tel 
command that 1s equivalent to the preceding wnite loop: 


while {$val>0} { 
set result [expr $result*$val] 
incr val -1 


} 


When this command is evaluated, the Tcl interpreter knows nothing about 
the command except that it has three words, the first of which is a command 
name. The Tcl interpreter has no idea that the first argument to wiie is an 
expression and the second is a Tcl script. Once the command has been 
parsed, the Tcl interpreter passes the words of the command to wniie, which 
treats its first argument as an expression and the second as a Tcl script. If the 
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expression evaluates to nonzero, wniie passes its second argument back to 
the Tcl interpreter for evaluation. At this point the interpreter treats the 
contents of the argument as a script (1.e., 1t performs command and variable 
substitutions and invokes the expr, set, and incr commands). 

Now consider the following command: 


set {$val>-0} { 
set result [expr $result*$val] 
incr val -1 


} 


As far as the Tcl interpreter is concerned, the set command 1s identical to the 
while Command except that it has a different command name. The interpreter 
handles this command in exactly the same way as the wniie command, except 
that it invokes a different procedure to execute the command. The set 
command treats its first argument as a variable name and its second 
argument as a new value for that variable, so it will set a variable with the 
rather unusual name of svai>o. 

The most common mistake made by new Tcl users is to try to understand Tcl 
scripts in terms of a grammar; this leads people to expect much more 
sophisticated behavior from the interpreter than actually exists. For 
example, a C programmer using Tcl for the first time might think that the first 
pair of braces in the wniie command serves a different purpose from the 
second pair. In reality, there is no difference. In each case the braces are 
present so that the Tcl interpreter passes the characters between the braces 
to the command without performing any substitutions. 

Thus the entire Tcl “language” consists of about a dozen simple rules for 
parsing arguments and performing substitutions. The actual behavior of a Tel 
script is determined by the commands executed. The commands determine 
whether to treat an argument as a literal value, the name of a variable, a 
code block to execute, and so on. An interesting consequence of this is that a 
script can define commands implementing entirely new control structures, 
which is a feature not available in most other languages. 


1.7 Event Bindings 


The next example provides a graphical front end for the factoriai procedure. 
In addition to demonstrating two new widget classes, it illustrates Tk’s 
binding mechanism. A binding causes a particular Tcl script to be evaluated 
whenever a particular event occurs in a particular window. The -commana 
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option for buttons is an example of a simple binding implemented by a 
particular widget class. Tk also includes a more general mechanism that can 
be used to extend the behavior of widgets in nearly arbitrary ways. 

To run the example, copy the following script into a file factoriai.tci1 and 
invoke the file from your shell. 


#!/usr/bin/env wish 
proc factorial {val} { 

set result 1 

while {$val>0} { 

set result [expr $result*$val] 
incr val -1 

} 

return $result 
} 
entry .value -width 6 -relief sunken -textvariable value 
label .description -text "factorial is" 
label .result -textvariable result 
button .calculate -text "Calculate" \ 

-command {set result [factorial $value] } 
bind .value <Return> { 

-calculate flash 

.calculate invoke 
} 
grid .value .description .result -padx lm -pady 1m 
grid .calculate - - -padx lm -pady 1m 


This script produces a screen display like that in Figure 1.2. There is an 
entry widget in which you can click with the mouse and type a number. If 
you click the button labeled “Calculate,” the result appears on the right side 
of the window; the same occurs if you press the Return key in the entry. 


Figure 1.2 A graphical user interface that computes a factorial 


"A wish85 
12 factorial is 479001600 


Calculate 


This application consists of four widgets: one entry, one button, and two 
labels. Entries are widgets that display one-line text strings that you can edit 
interactively. The entry is configured with a -wiatn of «6, which means it is 
large enough to display about six digits, and a -re1iet Of sunken, which makes 
the entry appear sunken into the window. The -textvariabie option for each 
entry specifies the name of a global variable to hold the entry’s text—any 
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changes you make in the entry are reflected in the variable and vice versa. 
The .aescription label widget holds decorative text, and the .resuit label 
holds the result of the power computation. The -textvariabie option for .resuit 
causes it to display whatever string is in the global variable resuit and to 
update itself whenever the variable changes. In contrast, .aescription displays 
a constant string. 

The first gria command arranges the entry and two label widgets in a row 
from left to right. The -paax and -paay options make the display a bit more 
attractive by arranging for 1 millimeter of extra space on the left and right 
sides of each widget, and | millimeter of extra space above and below each 
widget. The m suffix specifies millimeters; you could also use - for 
centimeters, i for inches, p for points, or no suffix for pixels. 

The second gria command arranges the button in a second row. Because the 
widget name occurs as the first argument, the gridder allocates the first 
column of the row to the button. The two - arguments following the widget 
name indicate to the gridder that the space allocated to the button widget 
should span two additional columns. The gridder then centers the button 
widget inside its allocated space. 

The command creating the .caicuiate button occupies two lines in the script; 
the backslash at the end of the first line is a line-continuation character, 
which causes the newline to be treated as a space. The button’s -commana 
script connects the user interface to the factoriai procedure. The script 
invokes factorial, passing it the values in the entry and storing the result in 
the resuit variable so that it is displayed in the .resuit widget. 

The pina command has three arguments: the name of a widget, an event 
specification, and a Tcl script to invoke when the given event occurs in the 
given widget. <return> specifies an event consisting of the user pressing the 
return key on the keyboard (which is still labeled “Return” on Mac 
keyboards but typically labeled “Enter” on most other English keyboards 
these days). Table 1.1 shows a few other event specifiers that you might find 
useful. 


Table 1.1 Event Specifiers 
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Event specifer Meaning 


<Button-1> Mouse button 1 is pressed 

<1l> Shorthand for <Button-1> 

<ButtonRelease-1> Mouse button 1 is released 

<Double-Button-1> Double-click on mouse button 1 

<Key-a> Key a is pressed 

<a>Ora Shorthand for <Key-a> 

<Motion> Pointer motion with any (or no) buttons or modifier keys 
pressed 

<B1-Motion> Pointer motion with button 1 pressed 


The script for a binding has access to several pieces of information about 
the event, such as the location of the pointer when the event occurred. For an 
example, start up wisn interactively and enter the following command in it: 


bind . <Motion> {puts "pointer at %x,%y"} 


Now move the pointer over the window. Each time the pointer moves, a 
message is printed on standard output giving its new location. When the 
pointer motion event occurs, Tk scans the script for « sequences and 
replaces them with information about the event before passing the script to 
Tel for evaluation. sx is replaced with the pointer’s x-coordinate and <y is 
replaced with the pointer’s y-coordinate. 

The intent of a binding is to extend the generic built-in behavior of the entry 
(editing text strings) with an application-specific behavior. In this script, as 
a convenience we would like to allow the user to request the factorial 
calculation by pressing the Return key as an alternative to clicking the 
“Calculate” button. We could simply duplicate the button’s command script, 
but if we were to modify the command script later, we’d need to remember 
to replicate the change in the binding script as well. Instead, we provide a 
binding script that “programmatically clicks” the button. 

The binding script executes two commands called widget commands. 
Whenever a new widget is created, a new Tcl command is also created with 
the same name as the widget, and you can invoke this command to 
communicate with the widget. The first argument to a widget command 
selects one of several operations, and additional arguments are used as 
parameters for that operation. In this binding script, the first widget 
command flashes the button. (Depending on your system’s color scheme, you 
might not see the button flash.) The second widget command causes the 
button widget to invoke its -commana option just as if you had clicked the 
mouse button on it. 
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Each class of widget supports a different set of operations in its widget 
commands, but many of the operations are similar from class to class. For 
example, every widget class supports a configure Widget command that can 
be used to modify any of the configuration options for the widget. If you run 
the factorial.tc1 Script interactively, you could type the following command 
to change the background of the entry widget to yellow: 


.value configure -background yellow 


Or you could type 


.calculate configure -state disabled 


to make the button unresponsive to user interaction. 


1.8 Additional Features of Tcl and Tk 


The examples in this chapter have used almost every aspect of the Tcl 
language syntax, and they illustrated many features of Tcl and Tk. However, 
Tcl and Tk contain many other facilities that are not used in this chapter; all 
of these are described later in the book. Here is a sample of some of the 
most useful features that haven’t been mentioned yet: 
¢ Arrays, dictionaries, and lists—Tcl provides associative arrays and 
dictionaries for storing key-value pairs efficiently and lists for 
managing aggregates of data. 
¢ More control structures—Tcl provides several additional 
commands for controlling the flow of execution, such as evai, for, 
foreach, and switch. 
¢ String manipulation—Tcl contains a number of commands for 
manipulating strings, such as measuring their length, regular 
expression pattern matching and substitution, and format conversion. 
¢ File access—You can read and write files from Tcl scripts and 
retrieve directory information and file attributes such as size and 
creation time. 
¢ More widgets—Tk contains many widget classes besides those 
shown here, such as menus, scrollbars, a drawing widget called a 
canvas, and a text widget that makes it easy to achieve hypertext 
effects. 
¢ Access to other windowing features—Tk provides commands for 
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accessing all of the major windowing facilities, such as a command 
for communicating with the window manager (to set the window’s 
title, for example), a command for retrieving the selection, and a 
command to manage the input focus. 

¢ Interapplication communication—Tcl includes the ability to 
communicate between applications through interprocess pipes and 
TCP/IP sockets. 

¢ C interfaces—Tcl provides C library procedures that you can use to 
define new Tcl commands in C. (Tk provides a library that you can 
use to create new widget classes and geometry managers in C, but 
this capability is rarely used and so is not covered in this book.) 
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2. Tcl Language Syntax 


To write Tcl scripts, you must learn two things. First, you must learn the Tcl 
syntax, which consists of a dozen rules that determine how commands are 
parsed. The Tcl syntax is the same for every command. Second, you must 
learn about the individual commands that you use in your scripts. Tcl 
provides about 100 built-in commands, Tk adds several dozen more, and 
any application based on Tcl or Tk will add a few more of its own. You'll 
need to know all of the syntax rules right away, but you can learn about the 
commands more gradually as you need them. 

This chapter describes the Tcl language syntax. The remaining chapters in 
Part I describe the built-in Tcl commands, and Part II describes Tk’s 
commands. 


2.1 Scripts, Commands, and Words 


A Tcl script consists of one or more commands. Commands are separated 
by newlines or semicolons. For example, 


set a 24 
set b 15 


is a script with two commands separated by a newline character. The same 
script could be written on a single line using a semicolon separator: 


set a 24; set b 15 


Each command consists of one or more words, where the first word is the 
name of a command and additional words are arguments to that command. 
Words are separated by spaces or tabs, which are generally referred to as 
either whitespace characters or just whitespace. Each of the commands in 
the preceding examples has three words. There may be any number of 
words in a command, and each word may have an arbitrary string value. 
The whitespace that separates words is not part of the words, nor are the 
newlines and semicolons that terminate commands. 


2.2 Evaluating a Command 
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Tcl evaluates a command in two steps as shown in Figure 2.1: parsing and 
execution. In the parsing step the Tcl interpreter applies the rules described 
in this chapter to divide the command up into words and perform 
substitutions. Parsing is done in exactly the same way for every command. 
During the parsing step, the Tcl interpreter does not apply any meaning to 
the values of the words. Tcl just performs a set of simple string operations 
such as replacing the characters sinput with the string stored in the variable 
input; Tcl does not know or care whether the resulting word is a number or 
the name of a widget or anything else. 


Figure 2.1 The parsing and execution of Tcl commands 


string match "*at in*" Sinput 


( Tcl parser ) 


| string] Command 


Command string 


match 
Words 


*at in* | Arguments 


‘The Cat in the Hat 


( Command procedure (string) 


Lif Result 


In the execution step, meaning is applied to the words of the command. Tcl 
treats the first word as a command name, checking to see if the command is 
defined and locating a command procedure to carry out its function. If the 
command is defined, the Tcl interpreter invokes its command procedure, 
passing all of the words of the command to the command procedure. The 
command procedure assigns meaning to these words according to its own 
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needs; because each command does something different, each command 
applies different meaning to its arguments. 


Note 


The Tcl community uses the terms word and argument interchangeably 
to refer to the values passed to command procedures. The only 
difference between these two terms is that the first argument is the 
second word. 


The following commands illustrate some of the meanings that are commonly 
applied to arguments: 

* set a 122 
In many cases, such as the set command, arguments may take any form 
whatsoever. The set command simply treats the first argument as a variable 
name and the second argument as a value for the variable. The command sect 
122 a 1S valid, too: it creates a variable whose name is i22 and whose value 
IS a. 

* expr 24 / 3.2 
The expr command concatenates its arguments, and the result must be an 
arithmetic expression that follows the rules described in Chapter 4. Several 
other commands also take expressions as arguments. 


® lindex {red green blue purple} 2 
The first argument to iindaex is a /ist consisting of four values separated by 
spaces. This command returns the value of the element at index 2 in the list 
(actually the third element, »iue, as elements are numbered starting at 0). 
Tcl’s commands for manipulating lists are described in Chapter 6. 

* string length abracadabra 
Some commands, like string and the Tk widget commands, are actually 
several commands rolled into one. The first argument of the command 
selects one of several operations to perform and determines the meaning of 
the remaining arguments. For example, string 1ength requires one additional 
argument and computes its length, whereas string compare requires two 
additional arguments. Such a collection of commands is sometimes referred 
to as an ensemble. 

* button .b -text Hello -fg red 
The arguments after .» are option-value pairs that allow you to specify the 
options you care about and use default values for the others. 
When writing Tcl scripts, one of the most important things to remember is 
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that the Tcl parser doesn’t apply any meaning to the words of a command 
while it parses them. All of the preceding meanings are applied by 
individual command procedures, not by the Tcl parser. This approach is 
similar to that of most shell languages but different from most programming 
languages. For example, consider the following C program code: 


x=4; 
y =xH0; 


In the first statement C stores the integer value « in variable x. In the second 
statement C evaluates the expression «+10, fetching the value of variable « 
and adding io, and stores the result in variable y. At the end of execution, 
has the integer value 14. If you want to use a literal string in C without 
evaluation, you must enclose it in quotes. Now consider a similar-looking 
program written in Tcl: 


set x 4 
set y x+10 


The first command assigns the string « to variable x. The value of the 
variable need not have any particular form. The second command simply 
takes the string «+10 and stores it as the new value for y. At the end of the 
script, y has the string value «+10, not the integer value 14. In Tcl, if you want 
evaluation you must ask for it explicitly: 


set x4 
set y [expr $x+10] 


Evaluation is requested twice in the second command. First, the second 
word of the command is enclosed in brackets, which tells the Tcl parser to 
evaluate the characters between the brackets as a Tcl script and use the 
result as the value of the word. Second, a dollar sign has been placed before 
x. When Tcl parses the expr command, it substitutes the value of variable 
for the sx. If the dollar sign were omitted, expr’s argument would contain the 
string x, resulting in a syntax error. At the end of the script, y has the string 
value 14. 


2.3 Variable Substitution 


Tcl provides three forms of substitution: variables, commands, and 
backslashes. Each substitution causes some of the original characters of a 
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word to be replaced with some other value. The Tcl interpreter performs the 
substitutions before executing the command procedure. Substitutions may 
occur in any word of a command, including the command name itself, and 
there may be any number of substitutions within a single word. 


Note 


Substitutions do not affect the word boundaries of a command, even if 
the characters substituted contain whitespace characters such as 
spaces, tabs, or newlines. 


The first form of substitution is variable substitution. It is triggered by a 
dollar sign character, and it causes the value of a Tcl variable to be inserted 
into a word. For example, consider the following commands: 


set kgrams 20 
expr $kgrams*2.2046 
= 44.092 


The first command sets the value of the variable xgrams to 20. The second 
command computes the corresponding weight in pounds by multiplying the 
value of xgrams by 2.2046. It does this using variable substitution: the string 
skgrams 18 replaced with the value of the variable xorams, so that the actual 
argument received by the expr command procedure 1s 20*2.2046. 

Variable substitution can occur anywhere within a word and any number of 
times, as in the following command: 


expr $result*$base 


The variable name consists of all of the numbers, letters, and underscores 
following the dollar sign. Thus the first variable name (+esuit) extends up to 
the « and the second variable name (nase) extends to the end of the word. 
Variable substitution can be used for many purposes, such as generating new 
names: 


foreach num {1 23 45} { 
button .b$num 
} 
This example creates five button widgets, with names .»1, .»2, .»3, .»4, and 


.b5. 
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These examples show only the simplest form of variable substitution. Two 
other forms of variable substitution are used for associative array 
references and to provide more explicit control over the extent of a variable 
name (e.g., so that there can be a letter or number immediately following the 
variable name). These other forms are discussed in Chapter 3. 


2.4 Command Substitution 


The second form of substitution provided by Tcl is command substitution. 
Command substitution causes part or all of a word to be replaced with the 
result of a Tcl command. Command substitution is invoked by enclosing a 
command in brackets: 


set kgrams 20 
set lbs [expr $kgrams*2.2046] 
=> 44.092 


The characters between the brackets must constitute a valid Tcl script. The 
script may contain any number of commands separated by newlines or 
semicolons in the usual fashion. The brackets and all of the characters 
between them are replaced with the result of the script. Thus in the 
foregoing example the exp: command is executed while the words for set are 
parsed; its result, the string 44.092, becomes the second argument to set. As 
with variable substitution, command substitution can occur anywhere in a 
word, and there may be more than one command substitution within a single 
word. 


2.5 Backslash Substitution 


The final form of substitution in Tcl is backslash substitution. It 1s used to 
insert special characters such as newlines into words and also to insert 
characters such as ; and s without their being treated specially by the Tcl 
parser. For example, consider the following command: 
set msg Eggs:\ \$2.18/dozen\nGasoline:\ \$2.49/gallon 
=> Eggs: $2.18/dozen 


Gasoline: $2.49/gallon 


There are two sequences of a backslash followed by a space; each of these 
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sequences is replaced in the word by a single space, and the space 
characters are not treated as word separators. There are also two sequences 
of a backslash followed by a dollar sign; each of these is replaced in the 
word with a single dollar sign, and the dollar signs are treated like ordinary 
characters (they do not trigger variable substitution). The backslash 
followed by » 1s replaced with a newline character. 

Table 2.1 lists all of the backslash sequences supported by Tcl. These 
include all of the sequences defined for ANSI C, such as \+ to insert a tab 
character and \x7a to insert the character whose hexadecimal value is 
0x007d in the Unicode character encoding. (Chapter _5 describes the 
Unicode encoding in greater depth.) If a backslash is followed by any 
character not listed in the table, as in \s or \:, the backslash is dropped from 
the word and the following character is included in the word as an ordinary 
character. This allows you to include any of the Tcl special characters in a 
word without the characters being treated specially by the Tcl parser. The 
sequence \\ inserts a single backslash into a word. And a backslash 
followed by a space character inserts a space as a literal character, rather 
than treating it as word-delimiting whitespace. 


Table 2.1 Backslash Substitutions Supported by Tcl 


Backslash sequence Replaced by 

\a Audible alert (0x7) 

\b Backspace (0x8) 

\f Form feed (Oxc) 

\n Newline (Oxa) 

\r ‘Carriage return (Oxd) 

\t Tab(Ox9)t”™” 

\v Vertical tab (Oxb) 

\ooo Unicode character specified by 8-bit octal value 000 


(one, two, or three o’s) 


\xhh Unicode character specified by 8-bit hex value hh (any 
number of h’s, although all but the last two are ignored) 


\uhhhh Unicode character specified by 16-bit hex value hhhh 
(from one to four h’s) 


\newline whitespace A single space character 


The sequence backslash-newline can be used to spread a long command 
across multiple lines, as in the following example: 
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pack .base .labell .power .label2 .result \ 
-side left -padx lm -pady 2m 


The backslash and newline, plus any leading whitespace on the next line, 
are replaced by a single space character in the word. Thus the two lines 
together form a single command. 


Note 


Backslash-newline sequences are unusual in that they are replaced ina 
separate preprocessing step before the Tcl interpreter parses the 
command. This means, for example, that the space character that 
replaces backslash-newline will be treated as a word separator unless 
itis between double quotes or braces. 


2.6 Quoting with Double Quotes 


Tcl provides several ways for you to prevent the parser from giving special 
interpretation to characters such as s and the semicolon. These techniques 
are called quoting. You have already seen one form of quoting in backslash 
substitution. For example, \s causes a dollar sign to be inserted into a word 
without triggering variable substitution. In addition to backslash 
substitution, Tcl provides two other forms of quoting: double quotes and 
braces. Double quotes disable word and command separators, and braces 
disable all special characters. 

If the first character of a word is a double quote, the word is terminated by 
the next double-quote character. Note that the double quotes themselves are 
not part of the word; they are simply delimiters. If a word is enclosed in 
double quotes, then spaces, tabs, newlines, and semicolons are treated as 
ordinary characters within the word. The example from the previous section 
can be rewritten more cleanly with double quotes as follows: 


set msg "Eggs: \$2.18/dozen\nGasoline: \$1.49/gallon" 
=> Eggs: $2.18/dozen 
Gasoline: $1.49/gallon 


The \n in the example could also be replaced with an actual newline 
character, as in 
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set msg "Eggs: \$2.18/dozen 
Gasoline: \$1.49/gallon" 


but many consider the script more readable with \n. 

If the word does not start with a double-quote character, any double-quote 
character within the word is treated as a literal character, not a delimiter. 
For example, the following is a legal, but highly discouraged, usage of 
literal double-quote characters in Tel: 


puts This"is"poor"usage 
=> This"is"poor"usage 


Variable substitutions, command substitutions, and backslash substitutions 
all occur as usual inside double quotes. For example, the following script 
sets msg to a String containing the name of a variable, its value, and the 
square of its value: 


set a 2.1 
set msg "a is $a; the square of a is [expr $a*$a]" 
>a is 2.1; the square of a is 4.41 


If you would like to include a double quote in a word enclosed in double 
quotes, use backlash substitution: 


set name a.out 
set msg "Couldn’t open file \"S$name\"" 
=> Couldn’t open file "a.out” 


2.7 Quoting with Braces 


Braces provide a more radical form of quoting where all the special 
characters lose their meaning. If a word starts with an open brace, all the 
characters between it and the matching close brace are the value of the 
word, verbatim. No substitutions are performed on the word, and spaces, 
tabs, newlines, and semicolons are treated as ordinary characters. The 
example from Section 2.5 can be rewritten with braces as follows: 


set msg {Eggs: $2.18/dozen 
Gasoline: $1.49/gallon} 


The dollar signs in the word do not trigger variable substitution, and the 
newline does not act as a command separator. In this case \n cannot be used 
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to insert a newline into the word, because the \n would be included in the 
argument as is without triggering backslash substitution: 


set msg {Eggs: $2.18/dozen\nGasoline: $1.49/gallon} 
=> Eggs: $2.18/dozen\nGasoline: $1.49/gallon 


Note 


The only form of substitution that occurs between braces is for 
backslash-newline. As discussed in Section 2.5, backslash-newline 
sequences are actually removed in a preprocessing step before the 
command is parsed. 


Unlike double quotes, braces can be nested. This is very common for 
procedure definitions and control flow commands, where one or more of the 
arguments are scripts to evaluate. Because the script must appear as a single 
argument, it must be quoted. In turn the script argument might contain other 
control flow commands with their own script arguments. 


Note 


If a brace is backslashed, it does not count in finding the matching 
close brace for a word enclosed in braces. The backslash is not 
removed when the word is parsed. 


One of the most important uses for braces is to defer evaluation. Deferred 
evaluation means that special characters aren’t processed immediately by 
the Tcl parser. Instead they are passed to the command procedure as part of 
its argument. The command procedure then processes the special characters 
itself, often by passing the argument back to the Tcl interpreter for 
evaluation. For example, consider the following procedure, which counts 
the number of occurrences of a particular value in a list: 
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proc occur {value list} { 
set count 0 
foreach el $list { 
if $el==S$value { 
iner count 


} 
} 


return $count 


} 


The body of the procedure is enclosed in braces so that it is passed 
verbatim to proc. Thus the value of the variable 1:s¢ 1s not substituted at the 
time the proc command is parsed. This is necessary if the procedure is to 
work correctly: a different value must be substituted for siist each time the 
procedure is invoked. Note that braces nest, so that the last argument to proc 
extends up to the matching close brace. Figure 2.2 illustrates what happens 
when the following Tcl script is subsequently evaluated: 


occur 18 {1 34 18 16 18 72 1994 -3} 


Figure 2.2 A snapshot of nested scripts being evaluated 
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occur 18 {1 34 18 16 18 72 1994 -3} 
Y 
1 34 18 16 18 72 1994 -3 


-—_—_—_—_> set count 0 
foreach el $list { 
if $el==Svalue { 
incr count 
} 


return $count 


| 


Y 
el 
1 34 18 16 18 72 1994 -3 


if $el==S$value { 
incr count 
} 


if $el==$value { 
incr count 


incr count 


iner count 


The braces around the second argument to occur cause the entire list of 
numbers to be passed to occur as a single word. The Tcl procedure 
mechanism then passes the procedure’s body to the Tcl interpreter for 
evaluation. When Tel parses the soreacn command in the body, the value of 
the variable iist is substituted, but the last argument to foreach (the loop 
body) is enclosed in braces so no substitutions are performed on it. The 
foreach Command procedure sets the variable <1 to each element of the list in 
turn and calls the Tcl interpreter to evaluate the loop body for each element. 
As part of this evaluation, Tcl parses the :s command, substituting the values 
of the variables e1 and vaiue. In the snapshot shown in Figure 2.2, the is test 
succeeded, so iz evaluates the incr command. 
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2.8 Argument Expansion 


The example in Section 2.7 demonstrated passing a list as an argument to a 
procedure. In that case the list appeared literally on the command line. 
Commonly, the list value might be the result of a variable or command 
substitution. But because the Tcl interpreter makes substitutions in a single 
pass from left to right, the list value is treated as a single word; the spaces 
embedded in the list value are not regarded as word separators. 

In some situations the single-layer-of-substitutions rule can be a hindrance 
rather than a help. For example, the following script is an erroneous attempt 
to delete all files with names ending in ..: 


file delete [glob *.o] 


The gicb command returns a list of all file names that match the pattern +.o, 
such aS a.o b.o c.o. However, the entire list of files is passed to rite delete as 
a single argument; file deicte Silently fails because it cannot find a file 
named a.o ».o c.o. For file delete to work correctly, the result of gic» must be 
split into multiple words. You can accomplish this through argument 
expansion. 

If a word starts with the string ;+; followed by a non-whitespace character, 
Tcl removes the leading ;«} and parses and substitutes the rest of the word 
as it would any other word. After substitution, Tcl parses the word again, 
but without substitution, to verify that the content consists of one or more 
syntactically complete words. If this is the case, the words are added 
individually to the command being evaluated; otherwise, Tcl raises a syntax 
error. Thus, 


file delete {*}[glob *.o] 
would be equivalent to 


file delete a.o b.o c.0 


after the Tcl interpreter performs substitution and expansion of the argument. 
The +} syntax first appeared in Tcl 8.5. Prior versions require you to add 
layers of parsing explicitly if you want them. Remember that Tcl commands 
are evaluated in two phases: parsing and execution. The substitution rules 
apply only to the parsing phase. Once Tcl passes the words of a command to 
a command procedure for execution, the command procedure can do 
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anything it likes with them. Some commands reparse their words—for 
example, by passing them back to the Tcl interpreter. -vai is an example of 
such a command, and it provides an alternate solution to the problems with 


file delete: 


eval file delete [glob *.o] 


eval concatenates all of its arguments with spaces in between and then 
evaluates the result as a Tcl script, at which point another round of parsing 
and evaluation occurs. In this example evai receives three arguments: fite, 
delete, ANd a.o b.o c.o. It concatenates them to form the string ¢ite delete a.o 
b.o c.o. When this string is parsed as a Tcl script, it yields five words. Each 
of the file names is passed to rite delete aS a Separate argument, so the files 
are all removed successfully. See Section 8.6 for more details on the proper 
use of the evai1 command. 


2.9 Comments 


If the first nonblank character of a command is +, the + and all the characters 
following it up through the next newline are treated as a comment and 
discarded. Note that the hashmark must occur in a position where Tcl is 
expecting the first character of a command. If a hashmark occurs anywhere 
else, it is treated as an ordinary character that forms part of a command 
word: 


# This is a comment 


set a 100 # Not a comment 

@ wrong # args: should be "set varName ?newValue?" 
set b 101 ;# This is a comment 

=> 101 


The + on the second line is not treated as a comment character because it 
occurs in the middle of a command. As a result, the first set command 
receives six arguments and generates an error. The last + is treated as a 
comment character, since it occurs just after a command was terminated 
with a semicolon. 

Tcl’s simple, consistent syntax rules can have some _ unexpected 
consequences. The requirement that the hashmark starting a comment must 
occur in a position where Tcl is expecting a command implies that the 
following example is not a comment: 
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set example { 
# This is not a comment 


} 


Instead, all of the characters occurring between the braces are treated as a 
single argument and are used as the string value assigned to the variable by 
the set command. In contrast, consider the following example: 


if {$x < 0} { 
# This is a comment 
puts "The result is negative." 


} 


In this case, the Tcl parser identifies two brace-quoted arguments that it 
passes to the is command. The is command evaluates its first argument as a 
Boolean expression, and if the result is true, it invokes the Tcl interpreter 
recursively to execute the second argument as a Tcl script. It is during this 
recursive invocation of the Tcl interpreter that the line beginning with the 
hashmark is identified as a comment. 

Another consequence of Tcl’s consistent syntax rules is that braces that 
appear inside a comment often cause errors when you execute the code. 
Consider the following example: 


proc countdown {x} { 
puts "Running countdown" 
# Incorrectly comment out this code block { 
while { $x >= 0 } { 
puts "x = $x" 
iner x=, 


} 


When the Tcl interpreter parses this command, the ; at the end of the first 
line marks the beginning of a word. The matching } marking the end of the 
word occurs on the last line. The fact that the word contains a script is 
irrelevant; Tcl is only parsing the command line into a set of words at this 
point, and so it follows a simple process of finding the matching brace, 
taking into account any and all nested braces contained within the word. Tcl 
then passes the word to the proc command, which stores it as the script 
implementing the countdown procedure. 

It’s when you attempt to execute the countdown procedure that Tcl then parses 
and executes the script. After executing the first pues command, Tcl ignores 
the entire second line—including the brace—as a comment. The wniie 
command is well formed, with its script argument terminated by the ; 
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following the incr command. Because Tel then expects to find another 
command on the following line, the } character at the beginning of the line is 
interpreted as being the name of the command to execute, resulting in the 
following error: 


countdown 3 
= Running countdown 


x= 3 
% =iZ 
x= 1 
x 270 


@ invalid command name "}" 


Note 


In general, try to avoid including brace characters in comments. If you 
do include braces in comments, make sure that they are balanced; for 
every opening brace, have a corresponding close brace in the 
comment. 


The following example shows a code block correctly commented out. The 
braces are balanced within the comments: 


proc countdown {x} { 
puts "Running countdown" 
# while { $x >= 0 } { 


= puts "x = $x" 
# incr x -l 
# } 


} 


A common alternative for commenting out a well-formed, parsable block of 
code is to enclose it within an is command with a false condition: 


proc countdown {x} { 
puts "Running countdown" 
if o { 
while { $x >= 0 } { 
puts "x = $x" 
incr x -1 
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2.10 Normal and Exceptional Returns 


A Tcl command can complete in several different ways. A normal return is 
the most common case; it means that the command completed successfully 
and the return includes a string result. Tcl also supports exceptional returns 
from commands. An error is the most frequent form of exceptional return. 
When an error return occurs, it means that the command could not complete 
its intended function. The command is aborted and any commands that 
follow it in the script are skipped. An error return includes a string 
identifying what went wrong; the string normally is displayed by the 
application. For example, the following set command generates an error 
because it has too many arguments: 


set state West Virginia 


@ wrong # args: should be “set varName ?newValue?" 


Different commands generate errors under different conditions. For 
example, expr accepts any number of arguments but requires the arguments to 
have a particular syntax; it generates an error if, for example, parentheses 
aren’t matched: 


expr 3 * (20+4 
@ unbalanced open paren 
in expression "3 * (20+4" 


The complete exceptional return mechanism for Tcl is discussed in Chapter 
13. Tcl supports a number of exceptional returns other than errors, provides 
additional information about errors besides the error message mentioned 
previously, and allows errors to be “caught” so that the effects of the error 
can be contained within a piece of Tcl code. For now, though, all you need 
to know is that commands normally return string results, but they sometimes 
return errors that cause Tcl command interpretation to be aborted. 


Note 


You may also find the global errortnto variable useful. After an error 
Tcl sets errortnfo to hold a stack trace indicating exactly where the error 
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occurred. You can print out this variable with the command puts 


Serrorinfo. 


2.11 More on Substitutions 


The most common difficulty for new Tcl users is understanding when 
substitutions do and do not occur. A typical scenario is for a user to be 
surprised at the behavior of a script because a substitution didn’t occur 
when the user expected it to happen, or a substitution occurred when it 
wasn’t expected. However, you should find Tcl’s substitution mechanism to 
be simple and predictable if you just remember two related rules: 
1. Tcl parses a command and makes substitutions in a single pass from 
left to right. Each character is scanned exactly once. 
2. At most a single layer of substitution occurs for each character; the 
result of one substitution is not scanned for further substitutions. 
Tcl’s substitutions are simpler and more regular than you may be used to if 
you’ve programmed with Unix shells. When new users run into problems 
with Tcl substitutions, it is often because they have assumed a more complex 
model than actually exists. 
For example, consider the following command: 


set x [format {Earnings for July: $%.2f} $earnings] 
= Earnings for July: $1400.26 


The characters between ;; are scanned exactly once, during command 
substitution, and the value of the earnings variable is substituted at that time. 
It is not the case that Tcl first scans the whole set command to substitute 
variables, then makes another pass to perform command _ substitution; 
everything happens in a single scan. The result of the format command is 
passed verbatim to sect as its second argument without any additional 
scanning (for example, the dollar sign in ¢format’s result does not trigger 
variable substitution). 

One consequence of the substitution rules is that unless you use the ;+) 
syntax described in Section 2.8, all the word boundaries within a command 
are immediately evident and are not affected by substitutions. For example, 
consider the following script: 


set city "Los Angeles" 
set bigCity $city 
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The second set command is guaranteed to have exactly three words 
regardless of the value of the variable city. In this case city contains a space 
character but the space is not treated as a word separator. 

One final note: It is possible to use substitutions in very complex ways, but 
you should avoid doing so whenever possible. Substitutions work best when 
used in very simple ways such as set a sb. If you use too many substitutions 
in a single command, and particularly if you use many backslashes, your 
code will be unreadable and unreliable. In situations like these, it’s usually 
clearer and safer to break up the offending command into several commands 
that build up the arguments in simple stages. Tcl provides several 
commands, such as format, subst, and iist, to help manage complex 
substitution scenarios. Another approach to consider is creating procedures 
to isolate complex processing; the result is often more readable and 
maintainable than trying to do all processing “inline.” 
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3. Variables 


Tcl supports two kinds of variables: simple variables (often referred to as 
scalar variables) and associative arrays. This chapter describes the basic 
Tcl commands for manipulating variables and arrays, and it also provides a 
more complete description of variable substitution. 


3.1 Commands Presented in This Chapter 


This chapter discusses the following basic commands for manipulating 
variables: 

® append varName value ?value ...? 
Appends each of the vaiue arguments to the variable varname, in order. If 
varName doesn’t exist, it is created with an empty value before appending 
occurs. The return value is the new value of varname. 


® incr varName ?increment? 


Adds increment to the value of the variable varname. Both increment and the old 
value of varvame must be integer strings (decimal, hexadecimal, or octal). If 
the argument is omitted, increment defaults to 1. The new value is stored in 
varName aS a decimal string and returned as the result of the command. As of 
Tcl 8.5, incrementing a nonexistent variable creates the variable and sets it 
to the increment value. 

® set varName ?value? 
If vaiue 18 specified, sets the value of the variable varvame tO vaiue. In any case 
the command returns the (new) value of the variable. 


® unset ?-nocomplain? ?--? varName ?varName varName ...? 


Deletes the variables given by the varwame arguments. Returns an empty 
string. Raises an error if any of the variables doesn’t exist, unless the - 
nocomplain option 1S included. 


® array exists arrayName 


Returns a Boolean value indicating whether the array called arrayname exists. 
® array get arrayName ?pattern? 
Returns a dictionary containing the contents of the array called arrayname. If 
pattern 1§ Specified, it restricts what elements are present in the dictionary to 
those whose keys match the pattern according to the rules of string matcn. 


® array names arrayName ?mode? ?pattern? 


89 


Returns a list of the names of elements within the array called arrayname. If 
pattern 1§ specified, it restricts what element names are returned by forming 
a glob pattern in the style of string match. If moae 1s also given, it should be 
either -exact, -glob, OF -regexp Meaning that exact matching (like string equat), 
glob matching (like string match, the default matching rule), or regular 
expression matching (like regexp) should be used to interpret pattern when 
selecting the element names. 

® array set arrayName dictionary 
Merges the contents of aictionary into the array called arraywame. Returns the 
empty string. 

® array size arrayName 


Returns the number of elements in the array called arrayname. 


® array statistics arrayName 


Returns a description of the internal configuration of the array named 
arrayName. 


® array unset arrayName ?pattern? 


Removes all elements that match pattern (according to the rules of string 
match) from the array named arraywame and returns the empty string. If pattern is 
absent, the whole array is unset. 


3.2 Simple Variables and the ... Command 


A simple Tcl variable has a name and a value. Both the name and the value 
may be arbitrary strings of characters. For example, it is possible to have a 
variable named xyz !# 22 OF march earnings: $100,472. In practice, variable 
names usually start with a letter and consist of a combination of letters, 
digits, and underscores, since that makes it easier to use variable 
substitution. Variable names, like all names in Tel, are case-sensitive: 
numwords refers to a different variable than wumworas. 

Variables may be created, read, and modified with the see command, which 
takes either one or two arguments. The first argument is the name of a 
variable, and the second, if present, is a new value for the variable: 


set a {Four score and seven years ago} 


=> Four score and seven years ago 
set a 
=> Four score and seven years ago 


set a 12.6 


— "en 
— Laer 
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Tcl variables are created automatically when they are assigned values. In 
this example, the first command creates a new variable a if it doesn’t 
already exist and sets its value to the character sequence Four score and seven 
years ago. The result of the command is the new value of the variable. The 
second set command has only one argument: a. In this form it simply returns 
the current value of the variable. The third set command changes the value 
of 2 to 12.6 and returns that new value. 


3.3 Tcl’s Internal Storage of Data 


Tcl variables can be used to represent many things, such as integers, real 
numbers, names, lists, and Tcl scripts, and many of these types of values 
have a very efficient internal representation. But all values have a string 
representation as well. The Tcl interpreter automatically converts the value 
between its internal and string representations on an as-needed basis. For 
example, if we create the variable 2 with the following command, Tcl stores 
only the string representation initially: 


seta 12.6 


During execution of the expr subcommand in the following command, Tcl 
parses the string value to generate an internal floating-point representation 
of the value in addition to the string value: 


set a [expr $a + 1.2] 


When the set command then assigns the return value of expr to a, only the 
floating-point internal representation exists. However, if you then use puts to 
print the value of 2 or otherwise treat the value of « as a string, Tcl generates 
a string representation of the value while maintaining the internal 
representation: 


puts $a 


Finally, if you modify the string representation of a, such as using appena to 
append characters to the end of the value, Tcl updates the string 
representation and discards the internal floating-point representation (even 
if the resulting string could be interpreted as a number): 


append a 32 
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The internal representation enables efficient handling of the value, and the 
string representation allows different values to be manipulated in the same 
way and communicated easily. Additionally, because all values appear to be 
strings at the scripting level, and the Tcl interpreter automatically manages 
memory allocation for values, there is no need for variable declarations. 
But by converting between string and internal representations only as 
needed, Tcl gains significant performance improvement. 


Note 


Most Tcl programs benefit from this automatic conversion between a 
value’s internal and string formats. However, if your program 
frequently changes a value while also executing commands. that 
alternate between the internal and string representations of the value, 
the conversion overhead can be noticeable. This effect, which is called 
“shimmering,” is most pronounced when manipulating large lists, 
particularly in tight loops. To minimize shimmering, try to manipulate 
the value with commands that do not modify the internal representation 
(e.g., use list commands to manipulate lists, arithmetic commands to 
manipulate numbers, etc.) and avoid forcing a string representation 
wherever possible. 


3.4 Arrays 


In addition to simple variables, Tcl also provides arrays. An array is a 
collection of elements, each of which is a variable with its own name and 
value. The name of an array element has two parts: the name of the array 
and the name of the element within that array. Both array names and element 
names may be arbitrary strings. For this reason Tcl arrays are sometimes 
called associative arrays to distinguish them from arrays in other languages 
where the element names must be integers. 

Array elements are referenced using notation like earnings (January), Where the 
array name (earnings 1n this case) is followed by the element name in 
parentheses (sanuary in this case). Arrays may be used wherever simple 
variables may be used, such as in the set command: 
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set earnings(January) 87966 
=> 87966 

set earnings(February) 95400 
=> 95400 

set earnings (January) 
=> 87966 


The first command creates an array named earnings, if 1t doesn’t already 
exist. Then it creates an element sanuary within the array, if it doesn’t already 
exist, and assigns it the value s7966. The second command assigns a value to 
the repruary element of the array, and the third command returns the value of 
the sanuary element. 


Note 


Don’t put quotes around the element name. If you do, the quote 
characters are interpreted as part of the element name, rather than as 
delimiting the element name. 


Although you can use array element names such as 0, 1, 2, etc., the names are 
still interpreted as strings rather than integer values. Therefore, an element 
name of : is not the same as 1.0. 

In Tcl, arrays are unordered data structures. (Internally, Tcl stores the array 
elements in a hash table.) Of course, you can assign element names that you 
can traverse in a particular order, using commands described later in this 
chapter. But if your intent is to design an ordered data structure, so that 
values maintain a given sequence, Tcl lists typically provide a better 
solution. See Chapter 6 for more information on Tcl lists. 


3.5 Variable Substitution 


Chapter 2 introduced the use of s notation for substituting variable values 
into Tcl commands. This section describes the mechanism in more detail. 
Variable substitution is triggered by the presence of an unescaped s 
character in a Tcl word. The characters following the s are treated as a 
variable name, and the s and name are replaced in the word by the value of 
the variable. Tcl provides three forms of variable substitution. So far you 
have seen only the simplest form, which is used like this: 
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expr $a+2 


In this form the s 1s followed by a variable name consisting of letters, digits, 
and underscores. The first character that 1s not a letter, digit, or underscore 
(. in the example) terminates the name. If the character immediately 
following a s is not a letter, digit, or underscore, the s is treated as a literal 
character. 

The second form of variable substitution allows array elements to be 
substituted. This form is like the first one except that the variable name is 
followed immediately by an element name enclosed in parentheses. 
Variable, command, and backslash substitutions are performed on the 
element name in the same way as a command word in double quotes. For 
example, consider the following script: 


set yearTotal 0 
foreach month {Jan Feb Mar Apr May Jun Jul Aug Sep \ 
Oct Nov Dec} { 
set yearTotal [expr $yearTotal+Searnings ($month) ] 


} 


In the expr command, searnings(smonth) 18 replaced with the value of an 
element of the array earnings. The element’s name is given by the value of the 
month Variable, which varies from iteration to iteration. 

An element name may contain whitespace characters, but the parentheses 
are not Tcl quoting characters, and so any unescaped whitespace characters 
are treated as word separators: 


set capital (New Jersey) Trenton 

@ wrong # args: should be "set varName ?newValue?" 
set capital("New Jersey") Trenton 

@ wrong # args: should be "set varName ?newValue?" 


The second example results in an error because the quote character doesn’t 
appear as the first character of the word, and so Tcl treats it as a literal 
character rather than a word delimiter. As a result, capitai("New 1S one word 
and sersey") another, and the set command receives too many arguments. 

To include a whitespace character in an element name, either escape the 
whitespace character or quote the entire variable reference: 


set capital (New\ Jersey) Trenton 
=> Trenton 

set "capital (South Dakota)" Pierre 
= Pierre 
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Another option is to use substitution for the element name. This works 
because substitutions do not affect the word boundaries of a command, even 
if the characters substituted contain whitespace characters; for example: 


set state "New Mexico" 
=> New Mexico 

set capital($state) "Santa Fe" 
=> Santa Fe 


The last form of substitution is used for simple variables in places where 
the variable name is followed by a letter or number or underscore. For 
example, suppose that you wish to pass a value such as 1.5m to a command as 
an argument, but the number is in a variable size (in Tk you might do this to 
specify a size in millimeters). If you try to substitute the variable value with 
a form like ssizem, Tcl will treat the m as part of the variable name. To get 
around this problem, you can enclose the variable name in braces as in the 
following command: 


.canvas configure -width ${size}m 


You can also use braces to specify variable names containing characters 
other than letters or numbers or underscores. 


Note 


Braces can be used to delimit only simple variables; there is no way to 
specify an element of an array with brace notation. 


Tcl’s variable substitution mechanism is intended to handle only the most 
common situations; there exist scenarios where none of the preceding forms 
of substitution achieves the desired effect. More complicated situations can 
be handled with a sequence of commands. For example, the format command 
can be used to generate a variable name of almost any imaginable form, set 
can be used to read or write the variable with that name, and command 
substitution can be used to substitute the value of the variable into other 
commands. 


Note 
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In general, restrict variable names to sequences of letters, digits, and 
underscore characters to make your code easier to write and read. 


3.6 Multidimensional Arrays 


Tcl implements only one-dimensional arrays, but multidimensional arrays 
can be simulated by concatenating multiple indices into a single element 
name. The following program simulates a two-dimensional array indexed 
with integers: 


matrix(1,1) 
matrix(1,2) 218 
matrix(1,3) 

at Se 

| 

cell Smatrix($i,$j) 


to nannnana a 
7 oO OO 
wy apa TDA) aren) 3 bed LOR A 


bs 


\J 


matrix 1S an array with three elements whose names are 1,1 and 1,2 and 1,3. 
However, the array behaves just as if it were a two-dimensional array; in 
particular, variable substitution occurs while the element name is scanned in 
the set command, so that the values of i and ; get combined into an 
appropriate element name. 


Note 


Spaces are significant in this example: matrix(1,1) refers to a different 
variable than matrix(1, 1). The best practice is to leave out the spaces, 
since they can also cause confusion during the parsing of commands. 
For example, the command 


set matrix(1, 1) 140 


is a command with four words, of which the third is 1). This results in 
three arguments to set, which then causes an error. The entire variable 
name would have to be enclosed in double quotes to get around this 
problem. 
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3.7 Querying the Elements of an Array 


The array command provides information about the elements currently 
defined for an array variable, as well as selected operations upon the whole 
array. It provides this information in several different ways, depending on 
the first argument passed to it. The command array size returns a number 
indicating how many elements are defined for a given array variable, and 
the command array names returns a list whose entries are the names of the 
elements of a given array variable: 


set currency(France) euro 
set "currency(Great Britain)" pound 
set currency(Japan) yen 
array size currency 
=> 3 
array names currency 
=> {Great Britain} Japan France 


For each of these commands, the second argument must be the name of an 
array variable. Optionally, you can provide an additional pattern argument, 
in which case the return value contains only those element names that match 
the pattern using the matching rules of the string match command (as 
described in Section 5.10). The list returned by array names does not have any 
particular order. 

The array names Command can be used in conjunction with foreach to iterate 
through the elements of an array. For example, this code deletes all elements 
of an array with values that are o or empty: 


foreach i [array names a] { 


if {($a($i) == "") || ($a($i) == 0)} { 
unset a($i) 
} 


Note 


The array command also provides a second way to search through the 
elements of an array, using the startsearch, anymore, nextelement, and 
donesearch Options. This approach is more general than the foreach 
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approach just given, and in some cases it is more efficient, but it is 
more verbose than the foreach approach and isn’t needed very often. See 
the reference documentation for details. 


The array exists Command can also be used to test whether a particular 
variable is an array, and the array get and array set commands can be used to 
convert between arrays and dictionaries: 


set a(head) hat 
set a(hand) glove 
set a(foot) shoe 
set apparel [array get a] 
=> foot shoe head hat hand glove 
array exists a 
=> 1 
array exists apparel 
=> 0 
array set b S$apparel 
lsort [array names b] 
= foot hand head 


3.8 The incr ANd appene Commands 


incr and appena provide simple ways to change the value of a variable. incr 
takes two arguments, which are the name of a variable and an integer. incr 
adds the integer to the variable’s value, stores the result back into the 
variable, and returns the variable’s new value as the result: 


set x 43 
incr x 12 
=> 55 


The number can have either a positive or a negative value. It can also be 
omitted, in which case it defaults to 1: 


set x 43 
incr x 
= 44 


Both the variable’s original value and the increment must be integer strings, 
in either decimal, octal (indicated by a leading 0), or hexadecimal 
(indicated by a leading ox). 
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Prior to Tcl 8.5, attempting to increment a variable that didn’t exist raised 
an error. As of Tcl 8.5, the behavior of incr changed to create the variable 
and set its value to the increment: 


incr y 
=> /] 

incr z 42 
=> 42 


The appena command adds text to the end of a variable. It takes two or more 
arguments, the first of which is the name of the variable; the remaining 
arguments are new text strings to add to the variable. It appends the new text 
to the variable and returns the variable’s new value. The following example 
USES appena to compute a table of squares: 


set msg "" 
foreach i {1 2 3 4 5} { 
append msg "$i squared is [expr $i*$i]\n" 


set msg 

Squared i 
squared i 
squared i 
squared i 
squared 1 


Wm Ww bo Bw 


Note 


The appena command does not automatically insert space characters 
between the text strings appended to the variable’s value. If you want a 
space character, you must explicitly include it as part of the text strings 
you provide as arguments. 


Neither incr nor appena adds any new functionality to Tcl, since the effects of 
these commands can be achieved in other ways. However, they provide 
simple ways to do common operations. In addition, appena 1s implemented in 
a fashion that avoids character copying. If you need to construct a very large 
string incrementally from pieces, it is much more efficient to use a command 
such as 


append x $piece 
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than a command such as 


set x "$x$piece" 


3.9 Removing Variables: unset and array unset 


The unset command destroys variables. It takes any number of arguments, 
each of which is a variable name, and removes all of the variables. Future 
attempts to read the variables result in errors just as if the variables had 
never been set in the first place. The arguments to unset may be either simple 
variables, elements of arrays, or whole arrays, as in the following example: 


unset a earnings(January) b 


In this case the variables 2 and » are removed entirely and the sanuary element 
of the earnings array is removed. The earnings array continues to exist after the 
unset Command. If a or » is an array, all of the elements of that array are 
removed along with the array itself. 

You can also delete elements from an array using the array unset Command, 
which accepts the name of an array variable and a pattern as arguments. 
Those element names that match the pattern using the matching rules of the 
string match Command (as described in Section 5.10) are deleted from the 
array. 


3.10 Predefined Variables 


The Tcl library automatically creates and manages several global variables. 
The reference documentation for tcivars describes all of these variables, but 
we’ ll examine the more frequently used ones in this section. 

When you invoke a tcish or wish script file, the name of the script file is 
stored in the variable arovo, the command-line arguments are stored as a list 
in the variable argv, and the number of command-line arguments is stored in 
the variable argc. Consider the following tcisn script: 


#!/usr/bin/env tclsh 


puts "The command name is \"Sargv0\"" 
puts "There were Sarge arguments: S$argv" 
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If you place this script in a file named printargs, make the file executable, 
and then invoke it from your shell, it will print out information about its 
arguments: 


printargs red green blue 
=> The command name is "printargs" 
=> There were 3 arguments: red green blue 


The variable env is predefined by Tcl. It is an array variable whose elements 
are all of the process’s environment variables. For example, the following 
command prints out the user’s home directory, as determined by the some 
environment variable: 


puts "Your home directory is $env(HOME)" 


The variable tc1_piatform 18 an array variable that contains several elements 
describing the platform on which the application is running, such as the 
name of the operating system, its current release number, and the machine’s 
instruction set: 


puts $tcl_ platform(platform) 
=> unix 

puts $tcl platform(os) 
= Darwin 

puts $tcl_platform(machine) 
= 1386 


This array can be quite useful when you are writing scripts that must run 
without change on both Windows and Unix. Based on the values in the array, 
you could execute any platform-specific code required for that platform. 


Note 


For versions of Mac OS prior to Mac OS X, the value of 
tcl_platform(platform) WaS macintosh. Starting with Mac OS X, the value is 
unix and the value of tci piatform(os) 1S Darwin, aS Shown above. For 
scripts that use Tk, you might have dependencies on the windowing 
system (for example, X11 versus Mac OS Aqua), in which case you 
can use the tx windowingsystem Command described in Chapter 29 to query 
the windowing system of the computer running the script. 
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3.11 Preview of Other Variable Facilities 


Tcl provides a number of other commands for manipulating variables. These 
commands will be introduced in full after you’ve learned more about the Tcl 
language, but this section contains a short preview of some of the facilities. 
The trace command ensemble can be used to monitor a variable so that a Tcl 
script gets invoked whenever the variable is set, read, or unset. Variable 
tracing is sometimes useful during debugging, and it allows you to create 
read-only variables. You can also use traces for propagation so that, for 
example, a database or screen display gets updated whenever the value of a 
variable changes. Variable tracing is discussed in Section 15.6. 

The gicba1 and upvar commands can be used by a procedure to access 
variables other than its own local variables. These commands are discussed 
in Chapter 9. 

The namespace command ensemble creates and manages namespaces, which 
are named collections of commands and variables. Namespaces encapsulate 
the commands and variables to ensure that they don’t interfere with the 
commands and variables in other namespaces. Namespaces are discussed in 


Chapter 10. 
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4. Expressions 


Expressions combine values (or operands) with operators to produce new 
values. For example, the expression 4+2 contains two operands, 4 and 2, and 
one operator, +; 1t evaluates to «. Many Tcl commands expect one or more of 
their arguments to be expressions. The simplest such command 1s expr, 
which just evaluates its arguments as an expression and returns the result as 
a string: 


expr (8+4) * 6.2 
=> 74.4 


Another example is is, which evaluates its first argument as an expression 
and uses the result to determine whether or not to evaluate its second 
argument as a Tcl script: 


if {$x <2} {set x 2} 


This chapter uses the exp. command for all of its examples, but the same 
syntax, substitution, and evaluation rules apply to all other uses of 
expressions as well. 


4.1 Commands Presented in This Chapter 


This chapter discusses the expr command: 
® expr arg ?arg arg...? 


Concatenates all the arg values (with spaces between), evaluates the result 
as an expression, and returns the expression’s value. 


4.2 Numeric Operands 


Expression operands are normally integers or real numbers. Integer values 
may be specified in decimal (the normal case), in binary (if the first two 
characters of the operand are ov), in octal (if the first two characters of the 
operand are oo), or in hexadecimal (if the first two characters of the operand 
are ox). For example, these are all ways of expressing the same integer 
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value: 335 (decimal), 00517 (octal), ox14e (hexadecimal), 0101001111 (binary). 
The octal and binary prefixes were added in Tel 8.5. 


Note 


For compatibility with older Tcl releases, an octal integer value is also 
indicated when the first character of the operand is simply 0, whether 
or not the second character is also o. Therefore, 0517 1s also equivalent 
to decimal 335. But 092 1s not a valid integer: the leading o causes the 
number to be read in octal, but » is not a valid octal digit. The safest 
way to force numeric values with possible leading zeros to be treated 
as decimal integers 1s with the scan command, discussed in Section 5.9. 
The page http://wiki.tcl.tk/498 on the Tcler’s Wiki shows some 
strategies for handling this, including the following procedure: 


proc forceInteger { x } { 
set count [scan $x {%d %c} n c] 
if { $count != 1 } { 
return -code error "not an integer: \"$x\"" 
} 


return $n 


You can specify real operands using most of the forms defined for ANSI C, 
including the following examples: 

21 

7.91e+16 


6E4 
3. 


Note 


These same forms are allowable not just in expressions but anywhere 
in Tcl that an integer or real value is required. 


Expression operands can also be non-numeric strings. String operands are 
discussed in Section 4.6. 
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4.3 Operators and Precedence 


Table 4.1 lists all of the operators supported in Tcl expressions; they are 
similar to the operators for expressions in ANSI C. Black horizontal lines 
separate groups of operators with the same precedence, and operators with 
higher precedence appear in the table above operators with lower 
precedence. For example, 4«2<7 evaluates to 0 because the « operator has 
higher precedence than <. Except in the simplest and most obvious cases you 
should use parentheses to indicate the way operators should be grouped; this 
helps prevent errors by you or by others who modify your programs. 


Table 4.1 Summary of Operators Allowed in Tcl Expressions 
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Syntax Result Operand types 


-2 Negative of a int, real 

+4 Unary plus of a int, real 

ta Logical NOT: 1 if ais zero, 0 otherwise int, real 

~a Bit-wise complement of a int 

at*b Exponentiation: a raised to the b power int, real 

a*b Multiply 4a and b int, real 

a/b Divide a by b int, real 

atb Remainder after dividing a by b int 

a+b Add a and b int, real 

a-b Subtract b from a int, real 

a<<b Left-shift a by b bits int 

a@>ob Arithmetic right-shift a by » bits int 

a<b 1 if a is less than b, 0 otherwise int, real, string 

a>b 1 if a is greater than b, 0 otherwise int, real, string 

acab 1 if a is less than or equal to », 0 otherwise int, real, string 

a>=b 1 if a is greater than or equal to b, 0 otherwise int, real, string 

a==b 1 if a is equal to b, 0 otherwise int, real, string 

alab 1 if ais not equal to b, 0 otherwise int, real, string 

aecgb 1 if a is equal to b, 0 otherwise string 

ane b 1 if a is not equal to b, 0 otherwise string 

ainb List containment: 2 if a is an element appearing in a: String; 2: list 
list &, 0 otherwise 

anib Negated list containment: 1 if a is not an element a: string; 2: list 
appearing in list b, 0 otherwise 

a&b Bit-wise AND of a and b int 

a“b Bit-wise exclusive OR of 4 and b int 

al|b Bit-wise OR of a and b int 

a&&b Logical AND: 1 if both a and bare nonzero, © int, real 
otherwise 

a||b Logical OR: 1 if either a is nonzero or b is nonzero, 0 int, real 
otherwise 

arb:e Choice; if a is nonzero then b, else ¢ a: int, real 


Operators with the same precedence group from left to right. For example, 
10-4-3 18 the same as (10-4)-3; both evaluate to 3. 


4.3.1 Arithmetic Operators 


Tcl expressions support the arithmetic operators +, -, «, /, «, and «». The - 
operator may be used either as a binary operator for subtraction, as in 4-2, or 
as a unary operator for negation, as in -(s*si). The / operator truncates its 
result to an integer value if both operands are integers. « is the modulus 
operator; its result is the remainder when its first operand is divided by the 
second. Both of the operands for = must be integers. «« is the exponentiation 
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operator, introduced in Tcl 8.5, which raises the first operand to the power 
of the second operand. 


Note 


The / and « operators have a more consistent behavior in Tcl than in 
ANSI C. In Tcl the remainder is always greater than or equal to zero 
and it has an absolute value less than the absolute value of the divisor. 
ANSI C guarantees only the second property. In both ANSI C and Tel, 
the quotient will always have the property that (x/y)*y + xy 18 x for all x 
and y. 


4.3.2 Relational Operators 


The operators < (less than), <= (less than or equal), >= (greater than or equal), 
> (greater than), -- (equal), and :- (not equal) are used for comparing two 
values. Each operator produces a result of : (true) if its operands meet the 
condition and o (false) if they don’t. These operators can be used for string 
as well as numeric comparisons; however, see Section 4.6 for more 
information on string comparison. 


4.3.3 Logical Operators 


The logical operators «x, ||, and : are typically used for combining the 
results of relational operators, as in the expression 


($x > 4) && ($x < 10) 


Each operator produces a o or : result. «s (logical AND) produces a : result 
if both its operands are nonzero, |; (logical OR) produces a : result if either 
of its operands is nonzero, and : (NOT) produces a : result if its single 
operand is zero. 

In Tcl, as in ANSI C, a zero value is treated as false and anything other than 
zero is treated as true. Tcl also accepts string representations of Boolean 
values: faise, no, OF oft for false, and truce, yes, OF on for true. These string 
representations are case-insensitive and may be unambiguously abbreviated. 
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Whenever Tcl generates a true/false value, though, it always uses 1 for true 
and o for false. 

As in C, the operands of <« and || are evaluated sequentially: if the first 
operand of «< evaluates to o, or if the first operand of |; evaluates to i, then 
the second operand is not evaluated. 


4.3.4 Bit-wise Operators 


Tcl provides six operators that manipulate the individual bits of integers: «, 
|, *, <<, >>, and ~. These operators require their operands to be integers. The 
s, |, and ~ operators perform bit-wise AND, OR, and exclusive OR: each bit 
of the result is generated by applying the given operation to the 
corresponding bits of the left and right operands. Note that « and | do not 
always produce the same results as <« and ||: 


expr 8& &2 
=>] 

expr 8&2 
> 0 


The operators << and >> use the right operand as a shift count and produce a 
result consisting of the left operand shifted left or right by that number of 
bits. During left shifts zeros are shifted into the low-order bits. Right- 
shifting is always “arithmetic right shift,’ meaning that it shifts in zeros for 
positive numbers and ones for negative numbers. This behavior is different 
from right-shifting in ANSI C, which is machine-dependent. 

The ~ operand (“ones complement”) takes only a single operand and 
produces a result whose bits are the opposite of those in the operand: zeros 
replace ones and vice versa. 


4.3.5 Choice Operator 


The ternary operator 2: may be used to select one of two results: 
expr {($a < $b) ? $a : $b} 


This expression returns the smaller of sa and sv. The choice operator checks 
the value of its first operand for truth or falsehood. If it is true (nonzero), the 
argument following the 2 is the result; if the first operand 1s false (zero), the 
third operand is the result. Only one of the second and third arguments is 
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evaluated. 


4.4 Math Functions 


Tcl expressions support mathematical functions, such as sin and exp. Math 
functions are invoked using standard functional notation: 


expr 2*sin($x) 
expr hypot($x, $y) + $z 


The arguments to math functions may be arbitrary expressions, and multiple 
arguments are separated by commas. See Table 4.2 for a list of all the built- 
in functions. 


Table 4.2 Predefined Mathematical Functions Supported in Tcl Expressions 
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Function Result 

abs (x) Absolute value of x 

acos (x) Arc cosine of x, in the range 0 to x 

asin (x) Arc sine of x, in the range ~n/2 to /2 
atan (x) AIC ta tangent of x, in the range -x/2 to x/2 


atan2 (x,y) 


Arc tangent of xi y, in the range > —n/2 to n/2 


bool (x) Converts any supported representation of Boolean true and false 
to 1 and 0 respectively 
ceil (x) Smallest integer not less than x 
cos (x) Cosine of x (xi in radians) 
. cosh (x) Hyperbolic cosine of x 
double (i) ‘Real value equal to integer : é 
exp (x) é raised to the power x 
floor (x) Largest integer not greater than x 
fmod (x, y) Real remainder of x divided by } y 
hypot (x, y) Square root of (x? + y?) 
int (x) integer value produced by truncating x toward 0 
log (x) Natural logarithm of x 
~ leglo (x) Base 10 logarithm of x 
. max (arg, ey Maximum value of all gi given numerical arguments 
“min (arg, ius ) Minimum value of all given numerical arguments 
pow (x, y) x raised to the power y 
rand () Pseudo- random floating- point value in the range [0,1) 
round (x) Integer value produced by rounding x 
sin(x) Sine of x (x in radians) 
sinh (x) Hyperbolic sine of x 
sqrt (x) Square root of x 
srand (x ) Resets the random number generator using integer seed x 
tan (x) Tangent of x (x in radians) 
tanh (x) “Hyperbolic tangent of x 
wide (x) Wide integer value ot x (at least 64 bits wide) 


As of Tcl 8.5, when the expression parser encounters a mathematical 
function such as sin(sx), it replaces the function internally with a call to an 
ordinary Tcl command in the tci::mathfunc namespace. (Tcl’s namespace 
feature is discussed in Chapter 10.) If the mathematical function contains 
comma-separated arguments, they are evaluated by expr and passed as 
separate arguments to the implementing procedure. Thus, the processing of 
an expression such as 


expr {sin($x+$y)} 
is the same in every way as the processing of 


expr {[tcl:mathfunc::sin [expr {$x+$y}]]} 
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and 


expr {atan2($y-0.3, $x/2)} 


is equivalent to 


expr {[tcl:mathfunc::atan2 [expr {$y-0.3}] [expr {$x/2}]]} 


Note 


The mechanism that maps functions to commands uses a relative 
namespace reference. If a namespace defines a command [namespace 
current]::tcl:: mathfunc::sin, Calls to sin in expressions evaluated in that 
namespace resolve to it in preference to Tcl’s predefined 


::tcl::mathfunc::sin. 


This capability allows you to define your own mathematical functions 
simply by creating new commands in the ¢tc1::matnfunc namespace. For 
example, to define a function to calculate the average of one or more 
numbers: 


proc tcl::mathfunc::avg {args} { 

if {[{llength $args] == 0} { 

return -code error \ 

"too few arguments to math function \"avg\"" 

} 
set total 0 
foreach val $args { 

set total [expr {$total + $val}] 


} 


return [expr {double($total) / [llength $args] }] 


} 


expr avg(2, 5, 1; 7) 
= 3.75 


4.5 Substitutions 


Substitutions can occur in two ways for expression operands. The first way 
is through the normal Tcl parser mechanisms, as in the following command: 
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expr 2*sin($x) 


In this case the Tcl parser substitutes the value of the variable « before 
executing the command, so the first argument to expr will have a value such 
aS 2*sin(0.8). The second way is through the expression evaluator, which 
performs an additional round of variable and command substitution on the 
expression while evaluating it. For example, consider the command 


expr {2*sin($x)} 


In this case the braces prevent the Tcl parser from substituting the value of «, 
so the argument to expr 18 2*sin(sx). When the expression evaluator 
encounters the dollar sign, it performs variable substitution itself, using the 
value of the variable x as the argument to sin. 


Note 


When the expression evaluator performs variable or command 
substitution, the value substituted must be an integer or real number (or 
a string, as described next). It cannot be an arbitrary expression. 


Having two layers of substitution doesn’t usually make any difference to the 
operation of the exp: command, but it is vitally important for other 
commands such as wniie that evaluate an expression repeatedly and expect to 
get different results each time. For example, consider the following script, 
which finds the smallest power of 2 greater than a given number: 


set pow 1 
while {$pow<$num} { 
set pow [expr $pow*?2] 


} 


The expression spow<snum gets evaluated by wniie at the beginning of each 
iteration to decide whether or not to terminate the loop. It is essential that 
the expression evaluator use a new value of pow each time. If the braces were 
omitted so that variable substitution is performed while parsing the wnite 
command—for example, white spow<snum. . .—then wniie’s argument would be 
a constant expression such as 1<44; either the loop would never execute, or it 
would execute forever. 
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Note 


Always quote your expressions with braces, even when using the expr 
command. Tcl is able to evaluate a braced expression much more 
efficiently than an unbraced expression. Quoting the expression with 
braces also prevents subtle security holes in your code. Consider a 
situation where a program prompts the user for a value, and then uses 
the value in an expression, such as 


set x [expr $input + 2] 


If a malicious user on a Windows system were to enter [format c:\1, the 
Tcl interpreter would substitute this string as the value of the input 
variable, and the expression evaluator would then execute the 
subcommand—formatting the C: drive. With the expression braced, the 
expression evaluator substitutes the value of the input variable; the 
result does not look like a valid arithmetic expression and so results in 
an error. 


4.6 String Manipulation 


Unlike expressions in ANSI C, Tcl expressions allow string operands for 
some operators, as in the following command: 


if {$x eq "New York"} { 
} 


In this example, the expression evaluator compares the value of the variable 
x to the string new york using the string equality operator; the body of the i+ is 
executed if they are identical. Strings are compared lexicographically. The 
sorting order may vary from system to system. 

To specify a string operand, you must either enclose it in quotes or braces or 
use variable or command substitution. It is important to enclose the entire 
expression in the preceding example in braces so that the expression 
evaluator substitutes the value of x. Consider the command 


set result [expr $x eq "New York"] 
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If the braces are left out, the arguments to expr are concatenated, resulting in 
the expression 


Los Angeles eq New York 


The expression parser is not able to parse tos (it isn’t a number, it doesn’t 
make sense as a function name, and it can’t be interpreted as a string 
because it doesn’t have quotes around it), so a syntax error occurs. 

If a string is enclosed in quotes, the expression evaluator performs 
command, variable, and backslash substitution on the characters between 
the quotes. If a string is enclosed in braces, no substitutions are performed. 
Braces nest for strings in expressions in the same way that they nest for 
words of a command. 

In addition to eq and ne, which explicitly test for string equality and 
inequality, you can perform string comparisons with the <, >, <=, >=, ==, and := 
operators. However, these other operators do string comparisons only if one 
or both of the operands cannot be parsed as a number. For example, 
consider the following script: 


set x 8 

set y 010 

expr {$x = $y} 
=> / 


Arithmetic comparison is used for the expr test, so the test evaluates to 1. 


Note 


If you want to compare two values as strings in a situation where they 
may both look like numbers (e.g., the values are stored in variables so 
you don’t know what their values are), you must use the string 
comparison operators or a command such as string compare, as 
described in Chapter 5. 


4.7 List Manipulation 


Tcl expressions also support two operators for list manipulation. (Chapter 6 
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discusses list manipulation in detail.) The in operator returns i if a 
particular string is an element in a list and o otherwise; the »: operator 
returns 1 if the string is not an element in the list and o otherwise. For 
example, the following tests whether tos angeles appears as an element in the 
list stored 1n cities: 


if {"Los Angeles" in $cities} { 
} 


The in and ni operators perform exact string comparison of the string against 
the list elements; they do no substring or pattern matching. Thus, the 
expression above is exactly equivalent to the following isearch -exact test: 


if {[lsearch -exact $cities "Los Angeles") != -1} { 


} 
4.8 Types and Conversions 


Tcl evaluates expressions numerically whenever possible. String operations 
are performed only for the string comparison operators and for the 
relational operators if one or both of the operands doesn’t make sense as a 
number. Most operators permit either integer or real operands, but a few, 
such as << and «, allow only integers. 

Tcl supports arbitrarily large integers, but for performance reasons integers 
are usually stored internally with the C type tong, which provides at least 32 
bits of precision on most machines. Tcl automatically uses an arbitrary- 
precision integer data type internally for integer values unable to fit 1n a 1ong 
value. Real numbers are represented with the C type aounie, which is usually 
represented with 64-bit values (about 15 decimal digits of precision) using 
the IEEE Standard for Binary Floating-Point Arithmetic. 

If the operands for an operator have different types, Tcl automatically 
converts one of them to the type of the other. If one operand is an integer and 
the other is a real, the integer operand is converted to real. If one operand is 
a non-numeric string and the other is an integer or real, the integer or real 
operand is converted to a string. 

Comparison operators always return a Boolean 0/1 result. The result of an 
arithmetic operation is a double if at least one of the operands is a double. 
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Integer arithmetic operations result in a native long integer if possible, or an 
arbitrary-precision integer otherwise. You can use the math function doubie to 
promote an integer to a real explicitly, and int, wide, entier, and rouna to 
convert a real value back to integer by truncation or rounding. The int 
function always returns a non-wide integer (converting by dropping the high 
bits). The wiae function always returns a wide integer (converting by sign 
extending if the argument is a 32-bit number, or dropping the high bits if the 
argument is larger than a 64-bit number). The entier function coerces its 
argument to an integer of appropriate size. entier 1S distinguished from int 
and wice in that int results in an integer limited to the low-order bits of the 
machine word size and wice 1s limited to 64 bits, whereas entier results in 
whatever size of integer is needed to hold the full value. 


4.9 Precision 


Numbers are kept in internal form throughout the evaluation of an expression 
and are converted back to strings only when necessary. Integers are 
converted to signed decimal strings without any loss of precision. Real 
numbers are converted using as few digits as possible while still 
distinguishing any floating-point number from its nearest neighbors. 


Ih? 


5. String Manipulation 


This chapter describes Tcl’s facilities for manipulating strings. Internally, 
Tcl stores strings as Unicode characters, but Tcl supports a variety of other 
character sets and can translate between character sets automatically and on 
demand. Tcl also supports handling binary strings. Tcl’s string manipulation 
commands include pattern matching in two different forms: one that mimics 
the rules used by shells for file name expansion and another that uses regular 
expressions as patterns. Tcl also has commands for formatted input and 
output in a style similar to the C procedures scant and prints. Finally, there 
are several utility commands for computing the length of a string, extracting 
characters from a string, case conversion, and other tasks. 


5.1 Commands Presented in This Chapter 


This chapter discusses the following commands for string manipulation: 

* binary format format ?value value ...? 
Returns a binary string whose layout is specified by format and whose 
contents come from the additional arguments. 

* binary scan string format varName ?varName varName ...? 
Parses fields from a binary string, returning the number of conversions 
performed. string 1s the input to be parsed, and format indicates how to parse 
it. Each varname gives the name of a variable; when a field is scanned from 
string, the result is assigned to the corresponding variable. 

® encoding convertfrom ?encoding? string 
Converts string to UTF-8 Unicode from the specified encoaing. If you omit 
encoding, the system encoding is used. 

® encoding convertto ?encoding? string 
Converts string from UTF-8 Unicode to the specified encoaing. If you omit 
encoding, the system encoding is used. 

® encoding names 
Returns a list of recognized encoding names. 

® encoding system ?encoding? 
Sets the system encoding to encoding. If you omit encoaing, the command 
returns the current system encoding. 


© format format ?value value ...? 
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Returns a result equal to format except that the vaiue arguments have been 
substituted in place of s sequences 1n format. 
° regexp ?options? exp string ?matchVar? ?subVar subVar ...? 

Determines whether the regular expression exp matches part or all of string 
and returns : if it does, o if it doesn’t. If there is a match, information about 
matching range(s) is placed in the variables named by matcnvar and the 
subvarS, 1f they are specified. See the reference documentation for a complete 
list of options. 


® regsub ?options? exp string subSpec ?varName? 


Matches exp against string aS for regexp and returns : if there 1s a match, o if 
there is none. Also copies string to the variable named by varvame, making 
substitutions for the matching portion(s) as specified by supspec. If you omit 
varName, the return value is the result of substitutions. See the reference 
documentation for a complete list of options. 


* scan string format varName ?varName varName ...? 


Parses fields from string as specified by format, places the values that match 
= sequences into variables named by the varvame arguments, and returns the 
number of fields successfully parsed. Alternatively, if no varvame arguments 
are provided, the values matched are returned as a list. 


® source ?-encoding encoding? fileName 


Reads and executes the script contained in the file riiename. Tcl reads the file 
using the system encoding unless you use -encoding to specify the encoding. 

* string bytelength string 
Returns the number of bytes used to represent the string internally. In most 
cases, you should use string iength instead. 

® string compare ?-nocase? ?-length num? stringl string2 
Returns -1, 0, or 1 1f seringi is lexicographically less than, equal to, or greater 
than string2. To ignore case, include the -nocase option. If you include -1engtn, 
then only the first num characters are used for comparison. 

* string equal ?-nocase? ?-length num? stringl string2 
Returns 1 if string and string2 are identical, 0 otherwise. To ignore case, 
include the -nocase option. If you include -iengtn, then only the first num 
characters are used for comparison. 


* string first stringl string2 ?startIndex? 


Returns the index in string of the first character in the leftmost substring that 
exactly matches stringi, or -1 1f there 1s no match. If startmmaex 18 specified, 
then the search is constrained to start with the character in string2 specified 
by the index. 


* string index string charIndex 


Returns the charrnaexth character of string, or an empty string if there is no 
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such character. The first character in string has index o. 
* string is class ?-strict? ?-failindex varname? string 

Returns i if string 18 a valid member of the specified character ciass; 
otherwise returns o. An empty string always returns : unless you include - 
strict, In Which case it returns o. If you include -failinaex, varname 18 assigned 
the index of the first character in string that was invalid for the specified 
class. The varname 18 not set if the command returns :. See the reference 
documentation for a list of recognized classes. 


* string last stringl string2 ?lastIndex? 


Returns the index in string2 of the first character in the rightmost substring 
that exactly matches stringi, or -1 if there is no match. If tastmaex is 
specified, only the characters in sering2 at or before the specified 1asttnaex 
will be considered by the search. 
* string length string 
Returns the number of characters 1n string. 
® string map ?-nocase? mapping string 
Returns the new string created by replacing substrings in string based on the 
mapping dictionary. Each instance of a mapping key in the string is replaced with 
the corresponding mapping value. The -nocase option causes case-insensitive 
matching. 


® string match ?-nocase? pattern string 


Returns 1 if pattern matches string using glob-style matching rules (+, 2, 1, 
and \) and o if it doesn’t. The -nocase option causes case-insensitive 
matching. 


® string range string first last 


Returns the substring of string that lies between the indices given by first 
and ias¢, inclusive. 

® string repeat string count 
Returns string repeated count number of times. 

* string replace string first last ?newstring? 
Returns the new string created by removing from string the range of 
characters from the first through iast indices inclusively, replacing them 
with newstring, 1f specified. 

® string tolower string ?first? ?last? 
Returns a value identical to string except that all uppercase characters have 
been converted to lowercase. The entire string is converted unless you 
specify the index of the first and/or iast characters to include in the 
conversion. 


* string totitle string ?first? ?last? 


Returns a value identical to string except that the first character 1s converted 
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to title case and the rest are converted to lowercase. The entire string 1s 
converted unless you specify the index of the first and/or iase characters to 
include in the conversion. 

® string toupper string ?first? ?last? 
Returns a value identical to string except that all lowercase characters have 
been converted to uppercase. The entire string is converted unless you 
specify the index of the rirse and/or iaste characters to include in the 
conversion. 

* string trim string ?chars? 
Returns a value identical to string except that any leading or trailing 
characters that appear 1n chars are removed. chars defaults to the whitespace 
characters. 


* string trimleft string ?chars? 


Same as string trim except that only leading characters are removed. 


* string trimright string ?chars? 


Same as string trim except that only trailing characters are removed. 


string wordend string charIndex 
Returns the index of the character just after the last one in the word 
containing character charmaex Of string. A word is either any contiguous 
range of letter, digit, and underscore characters, or any single character 
other than these. 

* string wordstart string charIndex 
Same aS string wordena except returns the index of the first character in the 
word containing character charinaex Of string. 


5.2 Extracting Characters: string inex AN string range 


Many string manipulation commands are implemented as options of the 
string Command. For example, string index extracts a character from a string: 


string index "Sample string" 3 
=p 


The argument after inaex 1s a string, and the last argument gives the index of 
the desired character in the string. For all string commands, an index of o 
corresponds to the first character of the string, 1 corresponds to the second 
character, and so on. The index ena refers to the last character of the string, 
ena-1 the next-to-last character, and so on. As of Tcl 8.5, you can also 
express an index by adding or subtracting two integer values. When using 
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the endtinteger OF integertinteger format, you cannot include any whitespace 
characters in the index argument, even if you quote the argument. If the index 
is outside the range of the string, string inaex returns an empty string: 


set i 2 

string index "Sample string" end-$i 
=eg 

string index "Sample string" 5+$i 
>s 

incr i 

string index "Sample string" 5+$i 
=> C 


The string range command is similar to string index except that it takes two 
indices and returns all the characters from the first index to the second, 
inclusive: 


> 


string range "Sample string" 3 7 
—ples 

string range "Sample string" 3 end 
= ple string 


5.3 Length, Case Conversion, Trimming, and 
Repeating 


The string 1ength Command counts the number of characters in a string and 
returns that number: 


string length "sample string" 
=> 13 


The string toupper command converts all lowercase characters in a string to 
uppercase, and the string tolower command converts all uppercase characters 
in its argument to lowercase: 


string toupper "Watch out!" 
=> WATCH OUT! 

string tolower "15 Charing Cross Road" 
= 15 charing cross road 


The string command provides three options for trimming: trim, trimiert, and 
trimright. Each option takes two additional arguments: a string to trim and an 
optional set of trim characters. The string trim command removes all 
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instances of the trim characters from both the beginning and the end of its 
argument string, returning the trimmed string as result: 


string trim aaxxxbab abc 
=> XXX 


The trimiert and trimrignt Options work in the same way, except that they 
remove the trim characters only from the beginning or the end of the string, 
respectively. The trim commands are most commonly used to remove excess 
whitespace; if no trim characters are specified, they default to the 
whitespace characters (space, tab, newline, carriage return, and form feed). 

Another utility string command is string repeat, Which returns a new string 
given an existing string and a repeat count: 


string repeat "*" 20 


> FF AA KHEAKRAAARAARAARARAR 
string repeat "abc" 5 
= abcabcabcabcabc 


5.4 Simple Searching 


The command string first takes two additional string arguments as in the 
following example: 


string first th "There is the tub where I bathed today" 
= 9 

string first th "There is the tub where I bathed today" 
=> 27 


It searches the second string to see if there is a substring that is identical to 
the first string. If so, it returns the index of the first character in the leftmost 
matching substring; if not, it returns -1. The search starts from the beginning 
of the second string unless you also provide an argument specifying the 
character index where the search should start. 

The command string iast 1S similar except it returns the starting index of the 
rightmost matching substring: 


string last th "There is the tub where I bathed today" 
=> 27 
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Note 


You can perform more complex searches using regular expressions, as 
discussed in Section 5.11. 


5.5 String Comparisons 


The command string compare takes two additional string arguments and 
compares them, returning o if the strings are identical, -1 if the first string 
sorts before the second, and : if the first string is after the second in sorting 
order: 


string compare Michigan Minnesota 
=> -1 

string compare Michigan Michigan 
=>0 


The string equal command does a simple string comparison of two strings, 
returning 1 if they are exactly the same and 0 if they aren’t. Both string compare 
and string equal are case-sensitive unless you specify the -nocase option. You 
can also provide an optional -1engtn option to specify that only the first 1engtn 
characters be used in the comparison: 


string equal cat cat 
=t 
string equal dog Dog 
=> 0 
string equal -nocase dog Dog 
=> 1 
string equal -length 3 catalyst cataract 
=> 1 


5.6 String Replacements 


You can perform a simple string replacement with the string replace 
command. It accepts a string as an argument along with the beginning and 
ending indices of a sequence of characters to delete, as well as an optional 
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string argument to insert in their place: 


string replace "San Diego, California" 4 8 "Francisco" 
=> San Francisco, California 

string replace "parsley, sage, rosemary, and thyme" 0 8 
=> sage, rosemary, and thyme 


The string map Command maps values within a dictionary to string sequences 
within your text, replacing the sequences with the values from the 
dictionary. This can be useful as a general templating facility. The basic 
syntax is 


string map dictionary string 


The string map command replaces all instances of the aictionary keys in the 
string With their corresponding values to return a new string. Replacement is 
done in an ordered manner, so the key appearing first in the list is checked 
first, and so on. The string is iterated over only once, so earlier key 
replacements have no effect on later matches; for example: 


set entities { 


& &amp; 
' §apos; 
> &gt; 
< &lt; 
\" &quot; 
} 
string map S$entities {if (index > 0 && nbAtts == 0) } 
=> if (index &gt; 0 &amp;éamp; nbAtts == 0) 


With the -nocase option, the keys are replaced regardless of case; for 
example: 


string map -nocase \ 
{ RESOURCE "Ms. Ripley" CORPORATION "Weyland-Yutani" } \ 
"Dear ResouRcE, welcome to your first day at corporation" 
=> Dear Ms. Ripley, welcome to your first day at Weyland-Yutani 


Note 


You can perform more complex replacements using regular 
expressions, as discussed in Section 5.12. 
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5.7 Determining String Types 


When manipulating strings, you often need to determine whether the value is 
in an appropriate format, such as whether it is numeric. To do so, use the 
string is Command, which analyzes a string and returns : if the string is a 
member of a given class of characters and o otherwise; for example: 


string is digit 1234 
=> 

string is digit "A man, a plan, a canal. Panama." 
=> 0 


By default, string is returns 1 for all character classes if the string 1s empty. 
Use the -strict option to force string is to return o if the string 1s empty: 


string is control "" 
=z 

string is control -strict "" 
> 0 


The -sai1index option allows you to specify a variable that gets set if the test 
fails. In this case, the command sets the variable to the index in the string of 
the first character that fails the test; for example: 
string is digit -failindex idx "123c5" 
= @ 
puts $idx 
=> 3 


Table 5.1 lists the character classes supported by the string is command. 


Table 5.1 Character Classes Supported by the string is Command 
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Class 


Tests 


alnum Only Unicode alphabet or digit characters 

alpha Only Unicode alphabet characters 

ascii Only 7-bit ASCII characters 

boolean A recognized form of Boolean value (0, false, no, of f, 1, true, 
yes, or on) 

control Only Unicode control characters 

Gigit Only Unicode digits 

Gouble A double-precision floating-point value (ignoring beginning or trail- 
ing spaces). If under- or overflow is detected, the - £ailindex vari- 
able is set to ~1. 

false A recognized form of the Boolean false value (9, false; no, off) 

craph Only nonspace Unicode printing characters - - 

“integer ~A32-bit integer value (ignoring beginning or trailing spaces). If under- 

or overllow is detected, the variable with -failindex gets set to -1. 

list A valid list structure. If the list structure is incorrect, the - fai lindex 
variable is set to the first element in the list where the structure failed, 

lower Only lowercase Unicode characters 

print Only Unicode printing characters (includes space) 

punct Only Unicode punctuation characters 7 

space Only Unicode space characters 

“true A recognized form of the Boolean true value (1, true, yes, or on) 
upper Only uppercase Unicode characters 


wideinteger 


A wide integer value (ignoring beginning or trailing spaces). it 
under- or overflow is detected, the -failindex variable is set to -1. 


wordchar Only alphanumeric or connecting punctuation characters (primarily 
the underscore) 
xdigit Only hexadecimal digit characters, including 0-9, a-£, and A-F 


Note 


The string is command tests against the Unicode definition of 
characters. For example, Unicode digits include more than the ASCII 
characters 0 through 9. 


5.8 Generating Strings with sormat 


Tel’s format Command provides facilities like those of the sprints procedure 
from the ANSI C library. For example, consider the following command: 


128 


format "The square root of 10 is %.3£" [expr sqrt(10)] 
=> The square root of 10 is 3.162 


The first argument to format 1S a format string, which may contain any number 
of conversion specifiers such as s.3<. For each conversion specifier, format 
generates a replacement string by reformatting the next argument according 
to the conversion specifier. The result of the format command consists of the 
format string with each conversion specifier replaced by the corresponding 
replacement string. In the preceding example, =.3¢ specifies that the next 
argument (the result of the expr command) is to be formatted as a real number 
with three digits after the decimal point. format supports almost all of the 
conversion specifiers defined for ANSI C sprintt, such as ¢a for a decimal 
integer, sx for a hexadecimal integer, and z- for real numbers in mantissa- 
exponent form. See the reference documentation for a complete list. 

The format command plays a less significant role in Tcl than prints and sprint¢ 
play in C. Many of the uses of prints and sprints are simply for conversion 
from binary to string format or for string substitution. Binary-to-string 
conversion isn’t needed in Tcl because values are already stored as strings, 
and substitution is already available through the Tcl parser. For example, the 
command 


set msg [format "%s is %d years old" $name $age] 


can be written more simply as 


set msg "$name is $age years old" 


The sa conversion specifier in the format command could be written just as 
well as zs; with sa, format converts the value of age to a binary integer, then it 
converts the integer back to a string again. 
format 18 typically used in Tcl to reformat a value to improve its appearance, 
or to convert from one representation to another (for example, from decimal 
to hexadecimal). As an example of reformatting, here is a script that prints 
the first ten powers of e ina table: 

puts "Number Exponential" 

for {set i1} {$i <= 10} {incr i} { 

puts [format "%$4d $12.3£" $i [expr exp($i)]] 


} 


This script generates the following output on standard output: 
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Number Exponential 

2.718 
7.389 
20.085 
54.598 
148.413 
403.429 
1096 .630 
2980.960 
8103.080 

22026.500 


owomo yd HU PWD 


= 


The conversion specifier 4a causes the integers in the first column of the 
table to be printed right-justified in a field 4 digits wide, so that they line up 
under their column header. The conversion specifier <12.3s causes each of 
the real values to be printed right-justified in a field 12 digits wide, so that 
the values line up; it also sets the precision at 3 digits to the right of the 
decimal point. 

The second main use for format, changing the representation of a value, is 
illustrated by the following script, which prints a table showing the ASCII 
characters that correspond to particular integer values: 


puts "Integer ASCII" 

for {set i 95} {$i <= 101} {incr i} { 
puts [format "%4d $c" $i $i] 

} 


This script generates the following output on standard output: 


Integer ASCII 
95 _ 
96 _ 
97 
98 
99 

100 
101 


7n90 0 gw 


The value of : is used twice in the format command, once with 4a and once 
with «c. The sc specifier takes an integer argument and generates a 
replacement string consisting of the ASCII character represented by the 
integer. 

An alternative to repeating the value of : in the preceding example is to use 
positional specifiers in the format string. If the « of a conversion specifier is 
followed by a decimal number and a s, as in s2sa, then the value to convert is 
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not taken from the next sequential argument. Instead, it is taken from the 
argument indicated by the number, where 1 corresponds to the first argument. 
With positional specifiers you can use the same argument as many times as 
desired. However, if there are any positional specifiers in the format string, 
all of the specifiers must be positional. So the following produces the same 
output as the previous script: 


puts "Integer ASCII" 

for {set i 95} {$i <= 101} {incr i} { 
puts [format "%1$4d %1$c" $i] 

} 


5.9 Parsing Strings with scan 


The scan command provides almost exactly the same facilities as the sscanr 
procedure from the ANSI C library. scan is roughly the inverse of format. It 
starts with a formatted string, parses the string under the control of a format 
string, extracts fields corresponding to = conversion specifiers in the format 
string, and places the extracted values in Tcl variables. For example, after 
the following command is executed, variable 2 has the value ic and variable 
» has the value 24.2: 


scan "16 units, 24.2% margin" "%d units, %f" a b 
> 2 


The first argument to scan 1s the string to parse, the second is a format string 
that controls the parsing, and any additional arguments are names of 
variables to fill in with converted values. The return value of 2 indicates 
that two conversions were completed successfully. 

scan Operates by scanning the string and the format together. Each character 
in the format must match the corresponding character in the string, except for 
blanks and tabs, which are ignored, and « characters. A « encountered in the 
format indicates the start of a conversion specifier: scan converts the next 
input characters according to the conversion specifier and stores the result 
in the variable given by the next argument to scan. Whitespace in the string is 
skipped except in the case of a few conversion specifiers such as «c. See the 
reference documentation for a complete description of conversion specifier 
syntax. 

One common use for scan is for simple string parsing, as in the preceding 
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example. Another common use is for converting ASCII characters to their 
integer values, which is done with the s- specifier. The following procedure 
uses this feature to return the character that follows a given character in 
lexicographic ordering: 


proc next c { 
scan $c %c i 
format tc [expr {$i+1}] 


} 


next a 
=>b 

next 9 
= 2: 


The scan command converts the value of the - argument from an ASCII 
character to the integer used to represent that character, then the integer is 
incremented and converted back to an ASCII character with the format 
command. 

Yet another typical use of scan is to force a string of digits with optional 
leading os to be interpreted as decimal integers, as the leading os usually 
cause Tcl to convert the string as an octal integer for arithmetic use. The 
following procedure forces a decimal interpretation of a numeric string: 


proc forceDecimal {x} { 
set count [scan $x {%lld %c} n c] 
if {$count != 1} { 
error "not an integer: \"Sx\"" 


} 


return $n 


} 


set val 0987 
expr { $val + 1 } 
@ can't use invalid octal number as operand of "+" 
expr { [forceDecimal $val] + 1 } 
=> 988 
forceDecimal xyz 
@ not an integer: “xyz" 


The format argument of the scan command in the forcepecima1 Implementation is 
designed to detect any nondigit characters after the digits. If you were to use 
only za as the format argument, the scan command would match the i23 in the 
string 123xyz. The 1:1 in the 11a conversion specifier is a size modifier 
supporting integers of unlimited precision. Without the 11 modifier, the 
converted value would be constrained to the machine word size of the 
system on which the script executes: 
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set val 0123456789012345678901234567890 
expr { $val + 1 } 

@ can't use invalid octal number as operand of "+" 
expr { [forceDecimal $val] + 1 } 

=> 123456789012345678901234567891 


5.10 Glob-Style Pattern Matching 


The simpler of Tcl’s two forms of pattern matching is called “glob” style. It 
is named after the mechanism for file name expansion in Unix shells, which 
is called “globbing.” Glob-style matching is easier to learn and use than the 
regular expressions described in the next two sections, but it works well 
only for simple cases. For more complex pattern matching you probably 
need to use regular expressions. 

The command string match Implements glob-style pattern matching: 


string match ?-nocase? pattern string 


The string match Command returns 1 1f the pattern matches the string, and o if it 
doesn’t. For the pattern to match the string, each character of the pattern 
must be the same as the corresponding character of the string, except that a 
few pattern characters are interpreted specially. For example, a « in the 
pattern matches a substring of any length, so r-i* matches any string whose 
first three characters are rc. Table 5.2 lists the special characters supported 
in glob-style matching. The match is case-sensitive unless you provide the - 
nocase Option. 


Table 5.2 Special Characters for Glob-Style Matching with the string match 


Command 
Character(s) Meaning 
* Matches any sequence of zero or more characters 
? Matches any single character 
[chars] Matches any single character in chars. If chars contains a sequence 


of the form a-b, any character between a and 5, inclusive, will match. 


\x Matches the single character x. This provides a way to avoid special 
interpretation for any of the characters *? [] \ in the pattern. 


The following examples illustrate the use of the string match command: 
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string match a* alphabet 
— 

string match a* bat 
= 0 


string match {[ab]*} brown 
1 

string match a* Arizona 

0 


string match -nocase a* Arizona 


— 

string match {*\?} "Wow!" 
=> 0 

string match {*\?} "What?" 
ig 


Many simple things can be done easily with glob-style patterns. For 
example, «.{ch) matches all strings that end with either .- or .». However, 
many interesting forms of pattern matching cannot be expressed at all with 
glob-style patterns. For example, there is no way to use a glob-style pattern 
to test whether a string consists entirely of digits: the pattern ,o-9) tests for a 
single digit, but there is no way to specify that there may be more than one 
digit. 


5.11 Pattern Matching with Regular Expressions 


Tcl’s second form of pattern matching uses regular expressions, which are 
more complex than glob-style patterns but also more powerful. Tcl’s regular 
expressions are based on Henry Spencer’s_ publicly available 
implementation, and parts of the following description are copied from 
Spencer’s documentation. 

Tcl supports three flavors of regular expressions called basic regular 
expressions (BREs), extended regular expressions (EREs), and advanced 
regular expressions (AREs). BREs and EREs exist mostly for backward 
compatibility. The EREs are defined in POSIX, and the AREs are inspired 
at least a bit by Perl. Ever since Tcl 8.1, all Tcl commands support the ARE 
syntax by default; therefore, the rest of this book describes the use of the 
ARE syntax. See the reference documentation for more information on BREs 
and EREs. 


Note 
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Regular expression syntax can be quite complex. This book presents 
elementary regular expression syntax and use in Tcl. You should read 
the reference documentation for a complete description of Tcl’s regular 
expression syntax. You can also learn more on web sites such as 
http://www.regular-expressions.info and http://regexlib.com. 
Additionally, the book Mastering Regular Expressions, Third Edition 
by Jeffrey E. F. Friedl (SBN 0-596-52812-4) provides an indepth 
examination of regular expression syntax and use. 


5.11.1 Regular Expression Atoms 


A regular expression pattern can have several layers of structure. The basic 
building blocks are called atoms, and the simplest form of a regular 
expression consists of one or more atoms. For a regular expression to match 
an input string, there must be a substring of the input where each of the 
regular expression’s atoms (or other components, as you'll see later) 
matches the corresponding part of the substring. In most cases atoms are 
single characters, each of which matches itself. Thus the regular expression 
abc Matches any string containing abc, Such aS abcde OF xabcy. 

A number of characters have special meanings in regular expressions; they 
are summarized in Table 5.3. The characters » and s are atoms known as 
constraints that match the position at the beginning and end of the input 
string, respectively. Thus «arc matches any string that starts with anc, abcs 
matches any string that ends in abc, and *apcs matches abc and nothing else. 
Similarly, the escape sequences \m and \w are constraints that match the 
beginning and end of a word, respectively. So \mcat\m matches only the word 
cat and not the cat 1N catalog OF concatenate. 


Table 5.3 Special Characters Permitted in Regular Expression Patterns 
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Character(s) 


Meaning 


Matches any single character 
Matches the null string at : the start of the input string 


Matches the null string at the end of the input string 


Matches the null String at the start of a word 


Matches the null string al the end ofa word 


Matches the nonalphanumeric character k (e.g., re matches a a literal 
. character) 


[chars] 


Where c is an alphanumeric character (possibly followed by other 
characters), represents an escape 


Matches ary single character from chars. It the first character of 
chars is *, the pattern matches any single character not in the 
remainder of chars. A sequence of the form a-bin chars is 
treated as shorthand for all of the ASCII characters between a and b, 
inclusive. If the first character in chazs (possibly following a *) is }, 
it is treated literally (as part of chars instead of a terminator). If a - 
appears first or last in chars, it is treated literally. 


{regexp) 


Matches anything that matches the regular expression regexp. 
Used for grouping and for identifying pieces of the matching 
substring. 


* 


Matches a sequence of zero or more matches of the preceding atom 


+. 


Matches a sequence of one or more matches of the preceding atom 


{in} 
{m,} 


Matches either a null string of a match of the preceding atom 
Matches a sequence of exactly. im matches of the preceding atom 
Matches a sequence of mor more matches of the preceding atom 


{m,n} 


rel| re2|... 


Matches a sequence of m through n (inclusive) matches of the pre- 
ceding atom 
Matches anything that matches any of the specified regular 


expressions 


The atom . matches any single character, and the atom \x, where « is any 
single character, matches x. For example, the regular expression .\s matches 
any string that contains a dollar sign, as long as the dollar sign isn’t the first 
character, and \.s matches any string that ends with a period. 

Tcl’s advanced regular expressions include an additional set of character- 
entry escapes, which also use the backslash character as a prefix. You can 
use these escape sequences as a means to specify otherwise hard-to-enter 
characters. Table 5.4 lists these special escapes. 


Table 5.4 Regular Expression Character-Entry Escape Sequences 
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Escape Represents 


\a The bell, or alert, character 

\b Backspace 

\B Backslash, same as \; used when needed to clean up regular expression 
syntax 

\cx Takes the lower 5 bits of the given character, x, and identifies the charac- 
ter with those lower 5 bits with all other bits zero 

\e Escape character 

\f£ Form feed 

\n Newline 

\r Carriage return 

\t Tab 

\uwxyz The Unicode character identified by the given four hexadecimal digits 

\v Vertical tab 

\xhhh The character whose ASCII value is represented by the given hexadecimal 
digits 

\o Null, or zero, character 

\xyz The character whose ASCII value is represented by the given two or three 


octal digits, as long as the value does not specify a back reference, as dis- 
cussed in the reference documentation 


Besides the atoms already described, there are two other forms for atoms in 
regular expressions. The first form consists of any regular expression 
enclosed in parentheses, such as (a.»). Parentheses are used for grouping, 
and a regular expression contained within a set of parentheses is often 
referred to as a subexpression or subpattern. They allow operators such as 
* to be applied to entire subexpressions as well as to atoms. They are also 
used to identify pieces of the matching substring for special processing. 
Both of these uses are described in more detail later. 

The final form for an atom is a range, which is a collection of characters 
between square brackets. A range matches any single character that is one of 
the ones between the brackets. Furthermore, if there is a sequence of the 
form a - » among the characters, all of the ASCII characters between a and » 
are treated as acceptable. Thus, the regular expression ,0-9a-sa-r) matches 
any string that contains a hexadecimal digit. If the character after the ; is a *, 
the sense of the range is reversed: it matches only characters not among 
those specified between the ~« and the }. 

Within the square brackets of a range, you also can use character class 
identifiers to represent all characters of a given class. For example, [:aipha:1 
within a range represents all alphabetic characters. Note that this goes 
beyond the idea of the ASCII letters (a-za-z) and encompasses all alphabetic 
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Unicode characters. Table 5.5 lists the available classes of characters. Note 
that you can combine an explicit set of characters with one or more 
character classes within a range definition, as in 


Table 5.5 Regular Expression Character Classes 


Class Represents 

{:alpha:] Alphabetic letter 

[:a lnum:] Alphanumeric letter or digit : 

{:blank:] Space or tab character 

{:entrl:] Control character 

(:digit:] Decimal digit 

{:graph:] Graphic character, a character with a visible representation such as a 
digit, alphabetic character, or punctuation 

{: lower: ] oe ~ Lowercase letter | 

{:print:] Printable character, which includes all of the class [:graph:] but 
adds the space character 

{:punct:] Punctuation character 

{:space:] Whitespace character 

{:upper: ] Uppercase letter 

{:xdigit:] Hexadecimal digit 


[[:alpha:][:blank:],;.!?] 


AS a convenience, you can also use one of the special escape sequences 
listed in Table 5.6 as a shorthand for various character classes. Note that the 
\w “word character” and its inverse \w escape sequences include _ as well as 
alphanumeric characters in their definitions. 


Table 5.6 Regular Expression Character Class Escape Sequences 


Escape Represents 
_\d {{:digit:]] 
_\D {(*[:digit:]] 

\s ({:space:]] 

\s (*[{:space:] ] 
\w [{:alnum:] ] 

\W (*[{:alnum:]_] 
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5.11.2 Regular Expression Branches and Quantifiers 


Regular expressions may be joined with the | operator. The resulting regular 
expression matches anything that matches any of the regular expressions 
separated by the |, which are referred to as branches. For example, the 
following pattern matches a string containing this, that, OF other: 


this|that|other 


Note that each branch may be any regular expression, including 
subexpressions, so it is possible to build quite complex structures. If two or 
more branches can match, Tcl prefers the longer match. To limit the extent of 
the branch definitions, you can enclose the set of branches within 
parentheses. For example, the following matches the string tn:s or the string 


that car: 


this|that car 


In comparison, the following matches the string this or that followed by car: 
(this|that) car 


The operators +, +, and 2 are known as quantifiers and may follow an atom 
to specify repetition. An atom followed by « matches a sequence of zero or 
more matches of that atom. An atom followed by + matches a sequence of 
one or more matches of the atom. An atom followed by » matches either an 
empty string or a match of the atom. For example, * (0x) 2(0-9a-sa-rj+s Matches 
strings that are proper hexadecimal numbers, that is, those consisting of an 
optional ox followed by one or more hexadecimal digits. 

Another set of quantifiers, known as bounds, allows you to specify exactly 
how many occurrences of an atom to match. Within a set of braces, you can 
specify the minimum and optionally the maximum number of occurrences, 
expressed as integers ranging from 0 to 255. {num} matches exactly num 
occurrences of an atom, {min,;} matches at least min occurrences, and (min, max} 
matches at least min but no more than max occurrences. 

When a regular expression can match more than one substring of a given 
string, the regular expression matches the one starting earliest in the string. 
Starting from that point, it then matches either the longest or the shortest 
substring possible, depending on the regular expression preference. By 
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default, the regular expression quantifiers are greedy, matching as many 
characters as possible. Any quantifier can be made non-greedy, and prefer 
the shortest substring possible, by following the quantifier with the > 
character. Thus, + and (3,7; are greedy quantifiers, whereas +2 and (3,7)? are 
non-greedy quantifiers. 


Note: 


In Tcl, you cannot mix greedy and non-greedy behavior within a single 
regular expression. The preference for the entire regular expression is 
determined by the preference of the first quantifier within the 
expression. Processing ambiguities can arise if mixed greediness is 
allowed, and so Tcl’s regular expression implementation was designed 
intentionally to disallow it. 


5.11.3 Back References 


In a regular expression, a back reference matches the same set of characters 
as matched by a previous subexpression. The syntax for a back reference is 
a \ followed by the number of the preceding subexpression. Subexpressions 
are numbered in order of their opening (left) parentheses. For example, the 
expression ((ab])\1 matches the string aa or »», but not ab or va. To illustrate, 
consider writing a regular expression that would match a string quoted in 
either single or double quotes. One approach would be to use two branches: 


! #N" *ON 


Alternatively, you can “capture” the first quoting character with a 
subexpression, then use a back reference to match the corresponding close 
quote: 


(").*2”\1 


Another example is that of finding accidentally repeated words, such as the 
the: 


\m(\w-+)\M\s+\m\1\M 
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5.11.4 Non-capturing Subexpressions 


Often you need subexpressions purely for “structural” purposes, such as 
delimiting branches or applying a quantifier to a sequence, but don’t need to 
use the subexpression for a back reference or for parsing, as discussed in 
the following sections. In these situations, you can use what’s often called a 
non-capturing subexpression, which has the form (2: expression). For 
example, the two following regular expressions match strings in the same 
way: 


((ab) {1,3}|(cd)+) xyz 
(?:(?:ab) {1,3}|(?:cd)+) xyz 


The advantage of non-capturing subexpressions is that the regular 
expression evaluates faster. The disadvantages are that a back reference 
cannot refer to a non-capturing subexpression, and the substring matching 
the non-capturing subexpression cannot be extracted into a separate match 
variable, as described in the next section. 


5.11.5 The regexp Command 


The regexp command invokes regular expression matching. In its simplest 
form it takes two arguments: the regular expression pattern and an input 
string. It returns o or 1 to indicate whether or not the pattern matches the 
input string: 


regexp {*[0-9]+S} 510 


=> 2 
regexp {*[0-9]+S} -510 
=f 


Note 


The pattern is enclosed in braces so that the characters s, :, and ; are 
passed through to the regexp command instead of triggering variable and 
command substitution. It is almost always a good idea to enclose 
regular expression patterns in braces. 
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If regexp 18 invoked with additional arguments after the input string, each 
additional argument is treated as the name of a variable. The first variable 
is filled in with the substring that matches the entire regular expression. The 
second variable is filled in with the portion of the substring that matches the 
first capturing subexpression within the pattern; the third variable is filled in 
with the match for the next capturing subexpression; and so on. If there are 
more variable names than capturing subexpressions, the extra variables are 
set to empty strings. For example, after executing the command 


regexp {([0-9]+) *([a-z}})} "Walk 10 km"a bc 


variable a has the value 10 xm,» has the value io, and - has the value xm. This 
ability to extract portions of the matching substrings allows regexp to be used 
for parsing. 

It is also possible to specify additional options to regexp before the regular 
expression argument. You can use the -start option followed by a character 
index into the string to instruct regexp to start looking for a match from that 
location. The -ai:1 option tells regexp to match the pattern as many times as 
possible in the string and return the total number of matches. A -nocase option 
specifies that alphabetic atoms in the pattern should match either uppercase 
or lowercase letters in the string. 

The -inaices option specifies that the additional variables should not be 
filled in with the values of matching substrings. Instead, each should be 
filled in with a list giving the first and last indices of the substring’s range 
within the input string. After the command 


regexp -indices {([0-9]+) *([a-z]+)} "Walk 10 km" \ 
abc 


the variable - has the value s 9, » has the value 5 «, and - has the value s 9. 
The -iniine option causes regexp to return as a list the data that it would 
otherwise place in match variables. For example, the following command 
returns a three-element list, where the first element contains the characters 
matching the entire expression and subsequent elements contain the 
characters matching each capturing subexpression: 


regexp {([0-9]+) *([a-z]+)} "Walk 10 km" 
=> {10 km} 10 km 


The -1ine option enables newline-sensitive matching. With this option, (> 
bracket expressions and . never match newlines, the ~» atom matches an 
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empty string after any newline in addition to its normal function, and the s 
atom matches an empty string before any newline in addition to its normal 
function. As an example, the following command returns a count of all lines 
beginning with optional spaces or tabs followed by the string error: 


regexp -all -line -- {[[:blank:]]*ERROR:} $text 


Note 


The regexp command also supports a -- option to explicitly mark the end 
of options. It is a good practice to always use the -- option; otherwise 
your pattern could mistakenly be interpreted as another option if its 
first character is a -. 


5.12 Using Regular Expressions for Substitutions 


Regular expressions can also be used to perform substitutions using the 
regsub Command. Consider the following example: 


regsub there "They live there lives" their x 
=> / 


The first argument to regsub 18 a regular expression pattern, and the second 
argument is an input string, just as for regexp. Also, like regexp, regsub returns 1 
if the pattern matches the string, o if it doesn’t. However, regsub does more 
than just check for a match: it creates a new string by substituting a 
replacement value for the matching substring. The replacement value is 
contained in the third argument to regsuv, and the new string is stored in the 
variable named by the final argument to regsu». Thus, after the preceding 
command completes, « has the value tey live their lives. If the pattern had 
not matched the string, 0 would have been returned and x would have the 
value they live there lives (the variable is set whether or not substitution took 
place). 

You can also provide one or more options preceding the regular expression 
argument, and many of the same options supported by regexp are also 
available for use with regsuv. Normally regsu» makes only a single 
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substitution, for the first match found in the input string. However, if -a11 is 
specified, regsub continues searching for additional matches and makes 
substitutions for all of the matches found. It then returns the number of 
substitutions made. For example, after the command 


regsub -alla ababa zz x 


x has the value zzbzzbzz. If -a11 were omitted, x would be set to zzbaba. 

The -nocase option requests a caSe-insensitive match of alphabetic atoms in 
the pattern. The -start option specifies a character index offset into the string 
where the pattern matching begins. The -iine option enables newline- 
sensitive matching, as with regexp. And you can use the -- option to explicitly 
mark the end of options to the command. 

In the preceding examples, the replacement string is a simple literal value. 
However, if the replacement string contains a « or \o, the « or \o 1s replaced 
in the substitution with the substring that matches the regular expression. Ifa 
sequence of the form \n appears in the replacement string, where » is a 
decimal number, the substring that matches the »th capturing subexpression 
is substituted instead of the \n. For example, the command 


regsub -all -- alb axaab && x 


doubles all of the @’s and »’s in the input string. In this case it sets x to 
aaxaaaabb. Alternatively, the command 


regsub -all -- (a+)(ba*) aabaabxab {z\2} x 


replaces sequences of a’s with a single z if they precede a » but don’t also 
follow a ». In this case « is set to zbaabxzb. Backslashes may be used in the 
replacement string to allow « \o, \n, or backslash characters to be 
substituted verbatim without any special interpretation. 


Note 


It’s usually a good idea to enclose complex replacement strings in 
braces as in the preceding example; otherwise the Tcl parser will 
process backslash sequences, and the replacement string received by 
regsub May not contain backslashes that are needed. 
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5.13 Character Set Issues 


A character encoding is simply a mapping of characters and symbols used 
in written language into a binary format used by computers. For example, in 
the standard ASCII encoding, the uppercase A character from the Latin 
character set is represented by the byte value 0x41 in hexadecimal. Other 
widely used character encodings include ISO 8859-1, used by many 
European languages, Shift-JIS and EUC-JP for Japanese characters, and 
Bigs for Chinese characters. 

The Unicode Standard is a uniform encoding scheme for virtually all 
characters used in the world’s major written languages. The text elements 
include letters such as w or M, characters such as those used in Japanese 
Hiragana to represent syllables, and ideographs such as those used in 
Chinese to represent full words or concepts. For more information on the 
Unicode Standard, visit the Unicode web site at http://www.unicode.org. 
UTF-8 is a standard transformation format for Unicode characters. It is a 
method of transforming all Unicode characters into a variable-length 
encoding of bytes; a single Unicode character can be represented by 1 or 
more bytes. The advantage of the UTF-8 standard 1s that it and the Unicode 
Standard were designed so that Unicode characters corresponding to the 
standard 7-bit ASCII set (up to ASCII value 0x7F in hexadecimal) have the 
same byte values in both UTF-8 and ASCII encoding. In other words, an 
uppercase A character is represented by the singlebyte value 0x41 in both 
UTF-8 and ASCII encoding. 

As of version 8.1, Tcl represents all strings internally as Unicode characters 
in UTF-8 format. Tcl also ships with built-in support for several dozen 
common character encoding standards and can convert strings from one 
encoding to another. The encoding names command returns a list of recognized 
encodings. The reference documentation describes how to add support for 
additional encodings. 


5.13.1 Character Encodings and the Operating System 


The system encoding is the character encoding used by the operating system 
for items such as file names and environment variables. Text files used by 
text editors and other applications are usually encoded in the system 
encoding as well, unless the application that produced them explicitly saves 
them in another format (for example, if you use a Shift-JIS text editor on an 
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ISO 8859-1 system). 

Tcl’s built-in commands automatically convert strings from UTF-8 format to 
the system encoding and vice versa whenever they communicate with the 
operating system. For example, Tcl automatically handles any encoding 
conversion needed if you execute commands such as 


glob * 
set fd [open "Espafol.txt" w] 
exec myprog << "|Bienvenido a Tcl!\n" 


By default, the Tcl source command reads files using the system encoding. If 
you have a script file stored in a character encoding other than the system 
encoding, you can use the source -encoding Option to provide the encoding 
name: 


source -encoding shiftjis script.tcl 


Tcl attempts to determine the system encoding during initialization, based on 
the platform and locale settings. Tcl usually can determine a reasonable 
default system encoding based on these settings, but if for some reason it 
cannot, it uses ISO 8859-1 as the default. 


Note 


You can override the default system encoding used by Tcl with the 
encoding system Command, but you should avoid using this command if at 
all possible. If you set Tcl’s default system encoding to anything other 
than the actual encoding used by your operating system, Tcl will likely 
find it impossible to communicate properly with your operating system. 


5.13.2 Encodings and Channel! Input/output 


When reading and writing data on a channel, you need to ensure that Tcl 
uses the proper character encoding for that channel. The default encoding 
for all newly opened channels is the same as the system encoding. In most 
cases, you don’t need to do anything special to read or write data because 
most text files are created in the system encoding. You need to take special 
steps only when accessing files in an encoding other than the system 
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encoding (for example, reading a file encoded in Shift-JIS format when your 
system encoding is ISO 8859-1). 
The fconfigure -encoding Option allows you to specify the encoding for a 
channel. Thus, to read from a file encoded in Shift-JIS format, you should 
execute the following commands: 


set fd [open $file r] 
fconfigure $fd -encoding shiftjis 


Tcl then automatically converts any text read from the file into standard 
UTF-8 format. Similarly, if you are writing to a channel, you can use 
fconfigure -encoding to specify the target character encoding, and Tcl will 
automatically convert strings from UTF-8 to that encoding on output. 


5.13.3 Converting Strings to Different Encodings 


You can convert a string to a different encoding using the encoding convertfrom 
and encoding convertto Commands. The encoding convertfrom Command converts a 
string from a specified encoding into UTF-8 Unicode characters; the encoding 
convertto Command converts a string from UTF-8 Unicode into a specified 
encoding. In either case, if you omit the encoding argument, the command 
uses the current system encoding. 

As an example, the following command converts a string representing the 
Hiragana character HA from EUC-JP encoding into a UTF-8 string: 


set ha [encoding convertfrom euc-jp "\xA4\xCF"] 


5.14 Message Catalogs 


In addition to the issue of handling different character set encodings, another 
challenge faced in the development of internationalized applications is that 
of presenting localized interfaces to users and other applications. To assist 
in creating localized applications, Tcl ships with a msgcat package, which 
provides a set of functions for managing multilingual user interfaces. It 
allows you to define strings in a message catalog, which is independent 
from your application or package and which you can edit or localize without 
modifying the application source code. 

The basic principle of the nsgcat package is that you create a set of message 
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files, one for each supported language, containing localized versions of all 
the strings your application or package can display. Then in your application 
or package, instead of using a string directly, you call the ::msgeat::me 
command to return a localized version of the string you want. 


5.14.1 Using Message Catalogs 


To use message catalogs from within your application or package, you must 
first load the msgcat package with the command 


package require msgcat 


By default, Tcl attempts to determine the locale according to the user’s 
environment, as discussed in the msgcat reference documentation. If Tcl can’t 
determine the locale based on the user’s environment, the locale defaults to 
C. Optionally, you can call the ::msgcat::mclocale command to explicitly set 
the locale: 


smsgcat::mclocale ? newLocale? 


If you omit the newrocale argument, mciocaie returns the current locale. A locale 
string consists of a language code, an optional country code, then an 
optional modifier, all separated with _ characters. The country and language 
codes are specified in standards [SO-639 and ISO-3166. For example, the 
locale en specifies English, whereas en us specifies U.S. English and en cs 
specifies U.K. English. 


Note 


The mciocale command can be useful for implementing features such as a 
language menu, where users can select the language they want your 
application to display. 


The next step is to call ::msgcat::mcloaa to load the appropriate message files. 
The mcioaa command requires as an argument a directory containing your 
message files. The format of the messages files is described in the next 
section. 

After loading the message files, wherever in your script you would typically 
specify a string to display, use the ::msgcat::me command instead. The mc 
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command takes as an argument a source string and returns the translation of 
that string in the current locale. 

The following code fragment demonstrates how you could use the msgcat 
package ina script: 


package require msgcat 


# Use the default locale as determined by the system. 
# You could explicitly set the locale with a command such as 
# ::msgcat::mclocale "en GB" 


# Load the message files. In this example, they are stored 
in a subdirectory named "msgs" which is in the same 
# directory as this script. 


3 


:msgcat::mcload \ 
[file join [file dirname [info script]] msgs] 


# Display a welcome message 
puts [::msgcat::mc "Welcome to Tcl!"] 


In this example, instead of directly displaying the message we1come to tc1!, the 
application calls mc to retrieve a localized version of the string. The string 
returned by mc depends on the current locale. For example, in the es locale me 
could return the Spanish-language greeting ;sienvenido a Tcl! 

The me command performs a “best match” search to return a translation 
string. If it doesn’t find an exact match in the locale specified in the user’s 
environment or by the mctocate command, it checks successively more 
general locales for a match. For example, if the locale is en ca Funky, the 
locales en cp Funky, en cB, en, and «" (the empty string, corresponding to the 
root locale) are searched in order until a matching translation string is found. 
If no match is found in any of those locales for the current namespace, mc 
checks the same set of locales for a match in the parent namespace, and so 
on until the global namespace is reached. This allows child namespaces to 
“inherit” messages from their parent namespace. (Tcl namespaces are 
discussed in Chapter 10.) 

If a translation string doesn’t exist for any of the locales in any of the 
namespaces, mc executes the procedure ::msgcat::mcunknown. The default 
behavior Of mcunknown 18 to return the original string (weicome to tc1! in this 
case), but you can redefine it to perform any action you want. 


5.14.2 Creating Localized Message Files 
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To use the msgcat package, you need to prepare a set of message files for your 
package or application, all contained within the same directory. The name 
of each message file is a locale specifier followed by the extension .msg (for 
example, es.msg for a Spanish message file or en gb.msg for a U.K. English 
message file). These file names must be all lowercase. The only exception 
is 1f you provide a message file for the root locale »", in which case it must 
be named zoor.msg. 


Note 


Defining a zoor.msg message file provides a fallback translation for all 
locales in the event one is not found in a more specific locale message 
file. This can be especially useful if you use symbolic source strings 
like tite notfouna In your Calls to me. 


Each message file contains a series of calls to ::msgcat::mcset and/or 
:imsgcat::memset to Set the translation strings for that language. The format of 
the meset Command is 


smsgcat::meset locale src-string ?translation-string? 


The mcset command defines a locale-specific translation for the given src- 
string. If NO transiation-string argument is present, then the value of src-string 
is also used as the locale-specific translation string. 

So, if American English is the “source language” for your application, an 
en_gb.msg file might contain commands such as 


::msgcat::mcset en GB "Welcome to Tcl!" 
::imsgcat::mcset en_GB "Select a color:" "Select a colour:" 


Note that no translation string is provided for the first line, so the resulting 
“translation” for the en_cs locale is the same as the American source string, 
Welcome to tcl! If you omitted this entry in the message file, then calling mc 
with the source string welcome to tc1! In the en cs locale would result in 
meunknown being called if no other translation were available using the “best 
match” process described in Section 5.14.1. Although the default behavior 
Of mcunknown Would produce the desired results (returning we1come to tc1!), YOU 
could run into problems if you override the behavior of mcunknown. Therefore, 
it is always safest to include a mapping for every source string in your 
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application, even if a particular locale doesn’t require a “translation” for 
that string. 
An equivalent Spanish-language message file, es.msg, might contain 


:imsgcat::mcset es "Welcome to Tcl!" ";Bienvenido a Tcl!" 
::msgcat::meset es "Select a color:" "Elige un color:" 


An alternative to using multiple mcset COMmmands is to use the :imsgcat: :mcmset 
command: 


smsgcat:memset locale translation-dict 


The transiation-aict 18 a Tcl dictionary structure, which is a whitespace- 
separated sequence of keys and associated values. (See Chapter 7 for more 
information on Tcl dictionaries.) The keys in the dictionary are your source 
strings, and the values are the translation strings for the locale. Keys and 
values containing whitespace characters should be quoted. The advantage of 
memset 18 that it can be significantly faster than a sequence of mcset calls. So, 
the preceding Spanish-language message file could be equivalently 
specified as 


::msgcat::mcemset es { 
"Welcome to Tcl!" ";Bienvenido a Tcl!" 
"Select a color:" "Elige un color:" 


5.14.3 Using Conversion Specifiers in Source and Translation Strings 


Sometimes you would like to insert one or more arguments into a localized 
string. In support of this, msgcat allows you to include conversion specifiers 
in the source and translation strings that are interpreted exactly as with the 
format Command described in Section 5.8. You can then pass values for these 
conversion specifiers as additional arguments to the m: command. 
As an example, consider an entry like this in a tr.msg message file: 


::msgcat::mcset fr \ 
"Directory contains #d files" "Il y a %*d fichiers" 


You could then use the translation in your application like this: 


puts [::msgcat::me "Directory contains %d files" $num] 
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Note: 


Positional specifiers can be especially useful with message files, as 
the order in which values are used might differ from language to 


language. 


5.14.4 Using Message Catalogs with Namespaces 


As discussed in Section 5.14.1, when you execute mc, it performs a “best 
match” search to return a translation string, for example, searching for a 
matching translation in the en cs locale before searching the en locale. It’s 
important to note that namespaces come into play during the lookup as well. 
If no matching translation is found in the current namespace, mc checks the 
same set of locales for a match in the parent namespace, and so on until the 
global namespace is reached. This allows child namespaces to “inherit” 
messages from their parent namespace. It also allows you to provide a set of 
translations specific to the library or module that you are developing if it is 
encapsulated in a namespace. (Tcl namespaces are discussed in Chapter 
10.) 

Translations in a message file that you register with mcset and memset are 
associated with the global namespace unless you explicitly execute those 
commands within a namespace eval Script. For example, if you are developing 
a library that uses the myiin namespace, you could register Spanish-language 
translations associated with that namespace in an es.msg file with code such 
as 

namespace eval Mylib { 
::msgcat::memset es { 


"Welcome to Tcl!" ";Bienvenido a Tcl!" 
"Select a color:" "Elige un color:" 


} 


A corresponding U.K. English message file, en gb.msg, Would contain code 
such as 
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namespace eval Mylib { 
::msgcat::memset en GB { 


"Welcome to Tcl!" "Welcome to Tcl!" 
"Select a color:" "Select a colour:" 
} 
} 
5.15 Binary Strings 


Tcl was designed to handle primarily textual data. The original assumption 
was that manipulation of structured binary data could be achieved by 
writing custom C functions that could then be exposed as custom Tel 
commands. However, working with binary data is common enough that the 
binary Command was added to Tcl to manage binary data. 

The binary format Command creates a binary string in a Tcl variable. In most 
cases, you then write the binary string to a channel, either to a file or to a 
network socket. With the binary format command, you specify a formatting 
string followed by the data to format: 


binary format formatString ?arg arg ...? 


The formatstring consists of a sequence of field specifiers, optionally 
separated by any number of spaces. Each field specifier consists of a 
character describing the type of data to format, optionally followed by a 
count of how many items of that type to format. The count defaults to : if 
omitted. For most types, a count of « indicates that all items in the associated 
argument should be used. 

Table 5.7 lists the different format types supported by the binary format 
command. Most of the types pertain to storing numerical information; for 
example: 


binary format c3 {1 2 120} 


Table 5.7 Format Types for the binary format and binary scan Commands 
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Format Usage 


a An 1SO 8859-1 (Latin-1) byte string of a given count. Uses only the low byte 
of Unicode characters. Pads with zero bytes as needed with binary format. 
A Same as a, but pads with spaces with binary format. Strips trailing 


spaces and nulls with binary scan, 
Binary digits as bytes, with the bits in low-to-high order within each byte 


b 
B Same as b, but with the bits in high-to-low order within each byte 
c 8-bit signed integer values 

d 


Double-precision floating-point values in the byte order native to the com- 
puter running the script (same as gq or Q) 


f£ Single-precision floating-point values in the byte order native to the com- 
puter running the script (same as r or R) 


h Hexadecimal digits in bytes in low-to-high order within each byte. Almost 
never used. 


Hexadecimal digits in bytes in high-to-low order within each byte 
32-bit signed integers in little-endian byte order 
Same as i but stores in big-endian byte order 


64-bit signed integers in the byte order native to the computer running the 
script (same as w or W) 


SinHir | x 


n 32-bit signed integers in the byte order native to the computer running the 
script (same as i or I) 


Double-precision floating-point values in little-endian byte order 
Same as q but stores in big-endian byte order 

Single-precision floating-point values in little-endian byte order 
Same as r but stores in big-endian byte order 


16-bit signed integers in little-endian byte order 
Same as s but stores in big-endian byte order 


16-bit signed integers in the byte order native to the computer running the 
script (same as = or S) 


64-bit signed integers in little-endian byte order 
Same as w but stores in big-endian byte order 


x Stores count null (0x00) bytes in the string with binary format; does 
not consume a value. Moves the cursor forward count bytes in the binary 
string with binary scan; a count of * means move to position 0. 


THIGDl/WirRK1O}/a 


= 


x Moves the cursor back count bytes in the binary string. A count of * 
means move to position 0. 

@ Moves the cursor to the specified byte position in the binary string, starting 
at position 0 


This command returns a binary string with the bytes \x01\x02\xe0. The c3 
format string means to format three 8-bit signed integers. If you provide 
additional formats, each value passed is expected to provide the data for a 
given format; for example: 


binary format I2a {1 -32 412534} E 
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The first format specifier, 12, takes only the first two numbers from the first 
argument, (1 -32 41234}, because of the count of 2, and stores them as 32-bit 
signed integers in big-endian order (most significant byte first). Following 
that, the second format specifier, 2, takes one character from the second 
value and stores it as an 8-bit Latin-1 character. 

The binary scan Command extracts data from a binary string: 


binary scan binaryString formatString ?varName varName ...? 


The formatstring consists of a sequence of field specifiers, optionally 
separated by any number of spaces. Each binary scan field specifier has the 
same format as with binary format, except that an optional u modifier can 
appear after the type character. The u indicates an unsigned value for integer 
fields; it’s ignored for noninteger fields. For each field specifier that 
consumes values from the binary string, you must provide the name of a 
variable to store the results of the conversion; otherwise the command 
raises an error. If you provide more variable name arguments than required, 
the excess variables are left untouched by binary scan. If a field specifier 
includes a count, that number of values of the specified type are read from 
the binary string and stored as a list in the corresponding variable (except 
for character-oriented types). If there are not enough bytes of data in the 
binary string to fulfill all of the field specifiers, the corresponding variables 
are left untouched. The return value of binary scan 1§ the number of variables 
set by the command. 

Here are some examples of extracting data from a binary string: 
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set data "\x40\x41\x42\x43\x44\x45\x46\x47\x48" 
binary scan $data a4c4 str chars 
=>2 
puts $str 
= GABC 
puts $chars 
=> 68 69 70 71 
binary scan $data a*c4 str2 chars2 
pe § 
puts $str2 
= @GABCDEFGH 
puts $chars2 
@ can't read “chars2": no such variable 
binary scan $data IS3 int shorts 
>1 
puts $int 
= 1078018627 
puts $shorts 
can't read "shorts": no such variable 
binary scan $data IS2 int shorts 
@O 2 
puts $int 
= 1078018627 
puts $shorts 
=> 17477 17991 
binary scan $data B8B5 bitsl bits2 
>2 


puts $bits1 

=> 01000000 
puts $bits2 

=> 01000 
binary scan $data H* hexl 
puts $hexl 

= 404142434445464748 
binary scan $data h* hex2 
puts $hex2 

= 041424344454647484 
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6. Lists 


Lists are used in Tcl to deal with collections of things, such as all the users 
in a group or all the files in a directory or all the options for a widget. Lists 
allow you to gather together any number of values in one place, pass around 
the collection as a single entity, and later get the component values back 
again. A list is an ordered collection of elements where each element can 
have any string value, such as a number, a person’s name, the name of a 
window, or a word of a Tcl command. Lists are represented as strings with 
a particular structure; this means that you can store lists in variables, type 
them to commands, and nest them as elements of other lists. 


6.1 Commands Presented in This Chapter 


This chapter describes the structure of lists and presents more than a dozen 
basic commands for manipulating lists. The commands perform operations 
like creating lists, inserting and extracting elements, and searching for 
particular elements. Later chapters describe additional commands that take 
lists as arguments or return them as results. 

* concat ?list list ...? 
Joins multiple lists into a single list (each element of each 1:s¢ becomes an 
element of the result list) and returns the new list. 

® Soin list ?joinString? 
Concatenates list elements with joinstring as the separator and returns the 
result. joinstring defaults to a space. 

® lappend varName value ?value...? 
Appends each vaiue to the variable varvame as a list element and returns the 
new value of the variable. Creates the variable if it doesn’t already exist. 

° lassign list varName ?varName ...? 
Assigns successive elements from 1is¢ to the variables given by the varname 
arguments in order. If there are more variable names than list elements, the 
remaining variables are set to the empty string. If there are more list 
elements than variables, a list of unassigned elements is returned. 

® lindex list ?index ...? 
Returns the inaexth element from iise (o refers to the first element). With 
multiple index values, either as separate arguments or as a list, each index 
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in turn selects an element from the previous indexing operation, allowing 
access to nested list elements. 

® linsert list index value ?value ...? 
Returns a new list formed by inserting all of the vaiue arguments as list 
elements before the inaexth element of 1:s¢ (o refers to the first element). 


list ?value value ...? 

Returns a list whose elements are the vaiue arguments. 
* llength list 

Returns the number of elements in ist. 


® lrange list first last 


Returns a list consisting of elements firse through 1ast Of 1ise. 


lrepeat number value ?value ...? 


Returns a list created by repeating the vaiue arguments as elements for number 
occurrences. 

* lreplace list first last ?value value ...? 
Returns a new list formed by replacing elements first through iase of iist 
with zero or more new elements, each formed from one vaiue argument. 

® lsearch ?option...? list pattern 
Searches for one or more elements in iist that match pattern. The option 
arguments control the pattern-matching style (-exact, -glob, -regexp), Whether 
to return element values (-iniine) or indices, whether to match all (-a11) or 
only the first occurrence in the list, and other behaviors. By default, 
performs glob matching, returning the index of the first match or -1 if no 
element matches. 

® lset varName ?index ...? newValue 
Sets the element specified by inaex of the list stored in varname tO newvalue. 
Returns the new list stored in varname. 

* lsort ?0ption ...? list 
Returns a new list formed by sorting the elements of 1ise. The switches 
determine the comparison function and sorted order (default: -ascii - 
increasing). 

® split string ?splitChars? 
Returns a list formed by splitting string at instances of spiitcnars and turning 
the characters between these instances into list elements. 


6.2 Basic List Structure and the iincx and iiengtn 
Commands 
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In its simplest form a list is a string containing any number of elements 
separated by any number of spaces, tabs, or newlines in any combination. 
For example, the string 


John Anne Mary Jim 


is a list with four elements. There can be any number of elements in a list, 
and each element can be an arbitrary string. In this simple form, elements 
cannot contain spaces, but there is additional list syntax that allows spaces 
within elements, as discussed later. 

The iinaex command extracts an element from a list: 


lindex {John Anne Mary Jim} 1 
=> Anne 


lindex takes at least two arguments, a list and an index, and returns the 
selected element of the list. For all list commands, an index of o 
corresponds to the first element of the list, 1 corresponds to the second 
element, and so on; the index ena refers to the last element of the list, ena-1 to 
the next-to-last element, and so on. As of Tcl 8.5, you can also express an 
index by adding or subtracting two integer values. When using the enat integer 
OF integert+integer format, you cannot include any whitespace characters in the 
index argument, even if you quote the argument. If the index is outside the 
range of the list, 1inaex returns an empty string. 

The i1iength command returns the number of elements in a list: 


llength {a b c d} 
=>4 
llength a 
<2 
llength {} 
=> 0 


As you can see from the examples, a simple string like 2 is a proper list with 
one element, and an empty string is a proper list with zero elements. 

When a literal list value is entered in a Tcl command, the list is usually 
enclosed in braces, as in the previous example. The braces are not part of 
the list; they are needed on the command line to pass the entire list to the 
command as a single word. When lists are stored in variables or printed 
out, there are no braces around them: 


set x {John Anne Mary Jim} 
=> John Anne Mary Jim 
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Braces and backslashes within list elements are handled by the list 
commands in the same way that the Tcl command parser treats them in 
words. This means that you can enclose a list element in braces if it contains 
spaces, and you can use backslash substitution to get special characters such 
as braces into list elements; for example: 


set testl {a b\ c d} 
llength $testl 
— 
lindex S$testl 1 
=D 
set test2 {a b\nc d} 
llength $test2 
= 3 
lindex $test2 1 
= ry 
Cc 
set test3 {a \} b \{ c} 
llength $test3 
=> 5 
lindex $test3 1 
a 


Note 


When building a list whose elements contain unusual characters, the 
1ist Command, discussed in the next section, is the safest way to ensure 
that the special characters receive proper quoting and escaping. 


Braces are often used to nest lists within lists, as in the following example: 


lindex {a b {c de} f} 2 
=>cde 


In this case element 2 of the list is itself a list with three elements. There is 
no intrinsic limit on how deeply lists may be nested. 

When manipulating nested lists, the 1inaex command allows you to specify 
one or more indices, either as separate arguments or as a list, to extract 
elements from sublists; for example: 
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set elements {{a b} {c {d e £}} g} 
lindex Selements 11 2 

=£ 
lindex $elements {0 0} 

>a 


The first example is equivalent to 


lindex [lindex [lindex $elements 1] 1] 2 
= 


though obviously shorter and less prone to errors. 


6.3 Creating Lists: lists concate and lrepeat 


Tcl provides three commands that combine strings to produce lists: 1ist, 
concat, aNd irepeat. Each of these commands accepts an arbitrary number of 
arguments, and each produces a list as a result. However, they differ in the 
way they combine their arguments. 

The iist command joins its arguments so that each argument becomes a 
distinct element of the resulting list: 


list {abc} {det f {ghit 
= {abc} {de} f fg hi} 


In this case, the result list contains only four elements. The 1ist command 
always produces a list with proper structure, regardless of the structure of 
its arguments (it adds braces or backslashes as needed), and the iinaex 
command can always be used to extract the original elements of a list 
created with 1ist. The arguments to 1ist need not themselves be well-formed 
lists. 


Note 


The iist command is the safe way to create a list if you don’t know 
what the element values are (for example, if you’ve prompted the user 
for input or are reading a value froma file). 


The concat command takes any number of lists as arguments and joins all of 
the elements of the argument lists into a single large list. If any of the 
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elements in a list argument is a nested list, the element retains its nesting 
structure: 


concat {a b c} {d e} £ {g h i} 
>abcdefghi 

concat {a b} {c {de f}} 
>a bci{de f} 


concat expects its arguments to have proper list structure; if the arguments are 
not well-formed lists, the result may not be a well-formed list either. In fact, 
all that concat does is to trim any leading and trailing whitespace characters 
from each of its argument strings and concatenate the result into one large 
string with space characters between the arguments. The same effect as 
concat Can be achieved using double quotes: 


set x {a b c} 

set y {d e} 

set z [concat $x Sy] 
>abcde 

set z "$x $y" 
=abede 


The irepeat command creates a list by repeating a set of elements, each 
occurring as a separate argument, a specified number of times; for example: 


lrepeat 3 a 
>aaa 
lrepeat 4 abe 
—~aebc'a.DB¢abc abc 
lrepeat 3 {a b} c 
=> {ab} c fa b} c fa b} c 


6.4 Modifying Lists: lrangeg linserts lreplaces lsets and lappend 


The irange command returns a range of elements from a list. It takes as 
arguments a list and two indices, and it returns a new list consisting of the 
range of elements that lie between the two indices (inclusive): 


set x {a b {c d} e} 
>a bicde 

lrange $x 1 3 
=>'b te dj e 

lrange $x 0 1 
>a b 
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The iinsert command forms a new list by adding one or more elements to an 
existing list: 


set x {a b {ec d} e} 
>a b{cd}e 

linsert $x 2 XY Z 
Sa.6 2-2 2 ae 

linsert $x 0 {X Y} Z 
= is ¥} Brae’ fe adi e 


linsert takes three or more arguments. The first is a list, the second is the 
index of an element within that list, and the third and additional arguments 
are new elements to insert into the list. The return value from 1insert 1s a list 
formed by inserting the new elements just before the element indicated by 
the index. If the index is o, the new elements go at the beginning of the list; if 
itis 1, the new elements go after the first element in the old list; and so on. If 
the index is greater than or equal to the number of elements in the original 
list, the new elements are inserted at the end of the list. 

The irepiace command deletes elements from a list and optionally adds new 
elements in their place. It takes three or more arguments. The first argument 
is a list and the second and third arguments give the indices of the first and 
last elements to be deleted. If only three arguments are specified, the result 
is a new list produced by deleting the given range of elements from the 
original list: 


Ireplace {a b {c d} e} 33 
=> ab {cd} 


If additional arguments are specified to irepiace, as in the following 
example, they are inserted into the list in place of the elements that were 
deleted: 


Ireplace {ab {cd} e} LZ {WXYZ 
>a{WX} YZe 


Note 


Tcl doesn’t have an explicit command for deleting elements from a list, 
as the irepiace command provides this functionality if you don’t provide 
any replacement element arguments. 
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A common operation is to update a list value stored in a variable by 
changing one of its elements. Historically, ircpiace has been used for this 
purpose, as in 


set person {{Jane Doe} 30 female} 
set person [lreplace $person 1 1 31] 
=> {Jane Doe} 31 female 


Because irepiace does not modify the value of a variable directly, you must 
perform command substitution to execute it, and then assign the result as the 
new value of the variable. Not only is this verbose, it is also inefficient, as 
lreplace Must copy the elements of the original list when creating the new 
list. This overhead can be pronounced when large lists are frequently 
updated. 

The iset command is an efficient and concise method for changing the value 
of an element when the list is stored in a variable. It accepts the name of a 
variable, an index to an existing element—or a series of indices to an 
element in a nested sublist—and the new value to assign to the element. isct 
returns the variable’s new value: 


lset person 1 32 
= {Jane Doe} 32 female 
lset person {0 1} Johnson 
= {Jane Johnson} 32 female 
lset person 0 0 Janice 
=> {Janice Johnson} 32 female 


Note 


You cannot use the iset command to create new list elements. It can 
only modify existing elements. iset returns an error if the index refers 
to a nonexistent element. 


The 1appena command provides an efficient way to append new elements to a 
list stored in a variable. It takes as arguments the name of a variable and any 
number of additional arguments. Each of the additional arguments is 
appended to the variable’s value as a new list element, and iappena returns 
the variable’s new value: 
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set x {a b {c d} e} 
=—ab {c d} e 


lappend x XxX {YY Zz} 


>a b {c d} e XX {YY 22} 
puts $x 
>a b {c d} e XX {YY 22} 


lappend 1S Similar tO appena except that it enforces proper list structure. As 
with appena, it isn’t strictly necessary. For example, the command 


lappend x $a $b $c 
could be written instead as 
set x [concat $x [list $a $b $c] 


However, as with appena, 1appena 18 implemented to optimize performance. 
For large lists, this can make a big difference. 


Note 


lappend and iset differ from other list commands such as irepiace in that 
the list is not included directly in the command; instead, you specify the 
name of a variable containing the list. 


6.5 Extracting List Elements: 1assicn 


The iassign Command is a convenience for distributing the values of a list 
among one or more variables. The first argument is a list, and all subsequent 
arguments are the names of variables. 1assign assigns successive elements 
from the list to the variables in order. If there are more variable names than 
list elements, the remaining variables are set to the empty string. If there are 
more list elements than variables, a list of unassigned elements is returned. 
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lassign {a b c} x y z ;# Produces an empty return value 
puts "<$x>, <S$y>, <$z>" 

=>:<a>; <b>; <e> 
lassign {de} xy z ;# Produces an empty return value 
puts "<$x>, <S$y>, <$z>" 

= <d>, <e>, <> 
lassign {f ghi} xy 

=>hi 
puts "<$x>, <S$y>" 

= <f£>, <g> 


Of course, similar results could be achieved with a series of tindex 
commands, though not as concisely: 


set x [lindex $vals 0] 
set y [lindex $vals 1] 
set z [lindex $vals 2] 


The behavior of iassign makes it easy to emulate the “shift? command of 
some languages: 


set argv [lassign $argv nextArg] 


Prior to Tcl 8.5, the foreach command was often used for its side effect of 
distributing list elements to individual variables. For example, to distribute 
the first three elements of the variable cooras to three separate variables: 


foreach {x y z} $coords { break } 


The preak command in this example serves as a “fail-safe” in case the list 
stored in coords consists of more than three elements. 


6.6 Searching Lists: isearcn 


The isearch command searches a list for an element with a particular value. 
It takes two arguments, the first of which is a list and the second of which is 
a pattern: 


set x {John Anne Mary Jim} 
lsearch $x Mary 

Tee” 
lsearch $x Phil 

— eae 


lsearch returns the index of the first element in the list that matches the 
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pattern, or -1 if there is no matching element. 

One of three different pattern-matching techniques can be selected by 
specifying one of the switches -exact, -giob, OF -regexp before the list 
argument: 


lsearch -glob $x A* 
=> ] 


The -gico switch causes matching to occur with the rules of the string match 
command described in Section 5.10. A -regexp switch causes matching to 
occur with regular expression rules as described in Section 5.11, and -exact 
insists on an exact match only. If no switch is specified, -gicb is assumed by 
default. You can also negate the sense of the match with the -not option. 

By default, isearcn finds only the first matching element. However, you can 
include the -a11 option to return all matching elements in the list: 


set states {California Hawaii Iowa Maine Vermont} 
lsearch -all $states *a 
=—0 2 


The -iniine option returns element values rather than indices. This is 
particularly useful when searching with patterns, as you then don’t need to 
USE 1index to extract the values in a separate step: 


lsearch -all -inline S$states *ai* 
= Hawaii Maine 


Note 


Remember that if you want to detect the presence or absence of an 
exact string value as an element in a list, you can use the in and n: 
operators respectively in an expression. See Section 4.7 for more 
information. 


6.7 Sorting Lists: isor 


The isort command takes a list as an argument and returns a new list with the 
same elements, but sorted by default in increasing lexicographic order: 
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lsort {John Anne Mary Jim} 
=> Anne Jim John Mary 


You can precede the list with any of several switches to control the sort. For 
example, -decreasing Specifies that the result should have the “largest” 
element first; -integer and -reai specify that the elements should be treated as 
integers or real numbers respectively and sorted according to value; - 
dictionary performs case-insensitive sorting and compares embedded digits 
as non-negative integers; and -unique discards all but the last occurrence of 
duplicated elements: 


lsort -decreasing {John Anne Mary Jim} 
= Mary John Jim Anne 
lsort {10 1 2} 
>1102 
lsort -integer {10 1 2} 
=> 2a ZO 
lsort {Peach banana Apple pear} 
=> Apple Peach banana pear 
lsort -dictionary {Peach banana Apple pear} 
=> Apple banana Peach pear 
lsort -dictionary {nll.gif nl.gif nl0.gif n9.gif} 
=>nil.gif n9.gif ni0.gif nil.gif 
lsort -unique {c ab qa z q} 
mabe dz 


If you have a nested list structure, the -inaex option allows you to specify the 
index of a sublist element on which to sort, rather than sorting on the entire 
subelement value: 


lsort -integer -index 1 {{First 24} {Second 18} {Third 30}} 
= {Second 18} {First 24} {Third 30} 


Additionally, for lists containing data that can’t be sorted lexicographically 
or numerically, you can use the -commana option to specify your own sorting 
function (see the reference documentation for details). 


6.8 Converting between Strings and Lists: .1:: and join 


The spiit command breaks a string into component pieces so that you can 
process the pieces independently. It creates a list whose elements are the 
pieces, so that you can use any of the list commands to process the pieces. 
For example, suppose a variable contains comma-separated values, and you 
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want to convert it to a list with one element for each component: 


set x "Anita Sanchez,35,VP Marketing" 
set y 39,72,,-17, 
split $x , 

=> {Anita Sanchez} 35 {VP Marketing} 
epiit Sy. 

=> 39 72 {} -17 f{} 


The first argument to spiit 1s the string to be split up, and the second 
argument contains one or more split characters. spiit locates all instances 
of any of the split characters in the string. It then creates a list whose 
elements consist of the substrings between the split characters. The ends of 
the string are also treated as split characters. If there are consecutive split 
characters, or if the string starts or ends with a split character as in the 
second example, empty elements are generated in the results. The split 
characters themselves are discarded. 


Note 


In practice, character-separated-value (CSV) data requires more 
careful handling, as the separator character might appear escaped as 
part of a value. Tcllib, the standard Tcl library, includes a csv package 
to handle CSV data properly. See Appendix B for more information on 
tcllib. 


Several split characters can be specified, as in the following example: 


split xbaybz ab 
xi yzZ 


If an empty string is specified for the split characters, each character of the 
string is made into a separate list element: 


split {a bc} {} 
=af{jbf{je 


The join command is approximately the inverse of spiit. It concatenates list 
elements with a given separator string between them: 
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join {{} usr include sys types.h} / 
= /usr/include/sys/types.h 

set x {24 112 5} 

expr [join $x +] 
=> 141 


join takes two arguments: a list and a separator string. It extracts all of the 
elements from the list and concatenates them with the separator string 
between each pair of elements. The separator string can contain any number 
of characters, including 0. In the first example here, a Unix-style path name 
is generated by joining the list elements with /. (The ite join command 
described in Chapter 11 is a better way to create paths in this manner, as it 
is platform-independent.) In the second example, a Tcl expression is 
generated by joining the list elements with +. 


6.9 Creating Commands as Lists 


A very important relationship exists between lists and commands in Tcl. A 
well-formed Tcl command has the same structure as a list. A list evaluated 
as a Tcl script consists of a single command whose words are the list 
elements. In other words, the Tcl parser performs no substitutions 
whatsoever. It simply extracts the list elements, and each element becomes 
one word of the command. This property is very important because it 
allows you to generate Tcl commands that are guaranteed to parse in a 
particular fashion even if some of the command’s words contain special 
characters such as spaces or s. 

For example, suppose you are creating a button widget in Tk, and when the 
user clicks on the widget you would like to reset a variable to a particular 
value. You might create such a widget with the following command: 


button .b -text Reset -command {set x 0} 


The Tcl script set x o 1s evaluated whenever the user clicks on the button. 
Now suppose that the value to be stored in the variable is not constant but 
instead 1s computed just before the button command and must be taken from a 
variable initvalue. Furthermore, suppose that initvaiue could contain any 
string whatsoever. You might rewrite the command as 


button .b -text Reset -command {set x $init Value} 


The script set x sinitvalue 1§ evaluated when the user clicks on the button. 
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However, this script uses the value of the global initvaiue variable at the 
time the user clicks on the button, which may not be the same as the value 
when the button was created. For example, the same variable might be used 
to create several buttons, each with a different intended reset value. Or, if 
the code to create the button were contained within a procedure, initvaiue 
might be a local variable that would not even exist at the time the user clicks 
the button, which would result 1n an error. 

To solve this problem, you must generate a Tcl command that contains the 
value of the initvaiue variable, not its name, and use this as part of the - 
command Option for the button command. Unfortunately, a simple approach like 


button .b -text Reset -command "set x $initValue" 


doesn’t work in general. If the value of initvaiue is something simple like 47, 
this works fine. The resulting command is set x 47, which produces the 
desired result. However, what if initvaiue Contains new york? In this case the 
resulting command is set x New york, Which has four words; set generates an 
error because there are too many arguments. Even worse, what if initvaiue 
contains special characters such as s or ;? These characters could cause 
unwanted substitutions to occur when the command is evaluated. 

The only solution that is guaranteed to work for any value of initvaiue 18 to 
use list commands to generate the command, as in the following example: 


button .b -text Reset -command [list set x $init Value] 


The result of the 11s: command is a Tcl command whose first word 1s set, 
whose second word is x, and whose third word is the value of the initvaiue 
variable in scope at the time the button is created (not when it is pressed). 
For example, suppose that the value of initvaiue 1S New york. The command 
generated by 1ist 1s 


set x {New York} 


which parses and executes correctly. Whatever value is present in initvaiue 
when the button command is invoked is assigned to x when the button is 
pressed, and this is guaranteed to work regardless of the contents of 
initvalue. Any of the Tcl special characters are handled correctly by 1ist: 
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set initValue {Earnings: $1410.13} 
list set x S$initValue 
=> set x {Earnings: $1410.13} 
set initValue "{ \\" 
list set x S$initValue 
=~setex VW AA 
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7. Dictionaries 


When you have a collection of things like a list but you wish to give each 
item a unique name and then access those items by their names, it is best to 
arrange the values into a dictionary. Like lists, dictionaries can contain any 
number of values, such as numbers, people’s names, window names, 
channels, or command names. Dictionaries collect these values into a single 
entity that you can pass around like any other value, or nest inside other 
dictionaries or lists, and then you can retrieve those component values again 
by looking them up by their key name. 

Dictionaries represent an ordered collection; dictionaries preserve the 
order of insertion of their keys and will iterate over them in that order. 
Dictionaries are represented as strings with a particular structure, looking 
just like a list with an even number of elements, and this means that you can 
store them in variables (including in array elements), type them into 
commands, and nest them inside themselves or lists. You can also put lists 
inside a dictionary, of course. 

Dictionaries differ from arrays in several fundamental ways. Arrays are 
unordered collections of variables, not values, and may not be nested. This 
means that only arrays can have traces set on elements, and only dictionaries 
can be reliably iterated over in the same order or passed as values to other 
commands (in particular, non-global arrays require the use of upvar or 
explicit packing and unpacking). 


Note 


The dictionary data type was introduced in Tcl 8.5 as a formalization 
of existing good practice that was present in the strings managed by the 
array COMmand’s get and set Subcommands, Tk widget options, and so 
on. The third-party aict extension provides a back port of most features 
of the aict command to Tcl 8.4, and earlier versions of Tcl can be 
supported through suitable scripts, though only 8.5 and later support 
efficient order-preserving dictionaries. 


7.1 Commands Presented in This Chapter 
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This chapter describes the structure of dictionaries and presents the aict 
command, which manipulates dictionaries. The subcommands of aict can 
look up particular elements; insert, replace, and remove them; and list the 
names in the dictionary, among other things. Later chapters describe 
additional commands that use dictionaries as arguments or return them as 
results. 


* dict append varName key value ?value ...? 
Appends the given string values to the vaiue associated with the xey in the 
dictionary contained 1n varname. 

© dict create key value ?key value ...? 
Creates a dictionary from the given xeys and vaiueS. If a key occurs twice or 
more in the list of arguments, the value associated with the last instance of 
the key is used. 


© dict exists dictionary key ?key ...? 
Tests whether the xey exists 1n the aictionary. Multiple keys may be given to 
test whether all the keys on a path through a group of nested dictionaries 
exist. 

® dict filter dictionary filterType ... 
Returns a new dictionary that is created from the supplied aictionary by 
applying the given filter. Filtering may be performed by matching (using 
string match rules) against keys or values or by using a script. 

® dict for {keyVar valueVar} dictionary body 
Iterates over the keys and values of the aictionary, setting the given variables 
to each of the keys and its associated value in turn, and then executing the 
boay argument for each of them. 

® dict get dictionary key ?key ...? 
Returns the value in the dictionary with the given xey. Multiple keys may be 
given to allow retrieval of a value from within nested dictionaries. 

® dict incr varName key ? increment? 
Increments the value in the dictionary in varvame with the given xey. If the 
increment is not given, it is i. If the key is not in the dictionary first, it is 
treated as if its value is o. 

© dict keys dictionary ?pattern? 
Returns a list of all the keys in the dictionary. If the pattern argument is 
specified, it returns only those keys that match the pattern according to the 
rules of string match. 

® dict lappend varName key value ?value ...? 
Appends the given list items to the value associated with the xey in the 
dictionary contained 1n varname. 


176 


© dict merge ?dictionary dictionary ...? 
Returns a new dictionary that is the combination of all the given 
dictionaries. Later key pairs override earlier key pairs when the keys 
correspond. 

© dict remove dictionary ?key ...? 
Returns a new dictionary that is the same as the supplied dictionary, except 
that each of the listed xeys is not present in it. It is not an error if a key is 
given that is not present in the original dictionary. 

* dict replace dictionary ?key value ...? 
Returns a new dictionary that is the same as the supplied dictionary, except 
that the given set of xey pairs will also form part of it (overriding any 
existing keys with the same names). 

® dict set varName key ?key ...? value 
Writes a new dictionary into the variable varname that is the same as the 
current contents of the variable, except that the given xey will map to the 
given value. Multiple keys may be given to allow update of a value within a 
nested dictionary. 

* dict size dictionary 
Returns the size (number of keys) of the given dictionary. 

® dict unset varName key ?key ...? 
Removes the mapping for the given «ey from the dictionary in the variable 
varName. Multiple keys may be given to allow removal of a value within a 
nested dictionary. If the mapping 1s not present, no error will be generated. 

© dict update varName key localVar ?key localVar ...? body 
For each of the listed xeys from the dictionary in varvame, binds its value to 
varname While the noay is being executed. When the boay finishes executing, the 
variable contents are written back to the dictionary. 

® dict values dictionary ?pattern? 
Returns a list of values from the aictionary. If pattern 18 given, only those 
values that match it (according to the rules of string matcn) are returned. 

® dict with varName ?key ...? body 
Binds each of the xeys in the dictionary 1n varname (or a subdictionary of it if a 
path of keys is given) to a local variable with the same name while soay is 
being executed. When boay finishes executing, the variable contents are 
written back to the dictionary. 


7.2 Basic Dictionary Structure and the act get 
Command 
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A dictionary is a structured value that looks just like a list with an even 
number of elements where the first, third, fifth (and so on) elements (the 
keys) are all distinct from each other. It is used to represent any collection 
of values that are indexed by strings, as opposed to lists, which are indexed 
by position. Dictionaries are used to represent structures (where the set of 
names is fixed) and maps (where the set of names is arbitrary). For 
example, the string 


firstname Joe surname Schmoe title Mr 


is a dictionary with three values (soe, schmoe, and mr) named by the keys 
firstname, surname, aNd titie respectively; it acts as a map from each of the 
keys to the value following it. There can be any number of elements in the 
dictionary, but each value must have a unique key. Both keys and values can 
be any arbitrary value. 

The aict get command extracts an element from a dictionary: 


set example {firstname Joe surname Schmoe title Mr} 
dict get Sexample surname 
= Schmoe 


dict get takes two arguments, a dictionary and a key to look up in the 
dictionary, and returns the value associated with that key; the command 
raises an error if the key does not have a value associated with it. The 
lookup of a value in a dictionary is very fast; behind the scenes, dictionaries 
are implemented as ordered hash tables, meaning that lookups are normally 
performed in nearly constant time. 

Just as with lists, when a dictionary is entered in a Tcl script, it 1s usually 
enclosed in braces. For a complicated dictionary, it is often easier to use 
line breaks to separate key-value pairs: 


set prefers { 
Joe {the easy life} 
Jeremy {fast cars} 
{Uncle Sam} {motherhood and apple pie} 


dict get $prefers Joe 
= the easy life 


In this case, the dictionary has three values (if it were a list, it would have 
six). You can also put dictionaries and lists inside each other as much as you 
wish; there is no limit imposed by the Tcl language. The next example maps 
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from employee numbers to structures containing the details of the 
employees; both the map and the structures are dictionaries: 


set employees { 


ooo1 { 
firstname Joe 
surname Schmoe 
title Mr 

} 

1234 { 
firstname Ann 
initial E 
surname Huan 
title Miss 


} 
puts [dict get [dict get Semployees 1234] firstname] 
=> Ann 


This example could have been implemented using arrays with structured 
keys. But when arrays are used in that way, either the record relating to each 
employee would have been a list (requiring special caution when extracting 
or updating), or there would have been no record representing the employee 
data as a whole; whenever you would need such a record (for example, to 
pass to a procedure), you would have to extract it from the overall array, 
which would require much greater overhead. By contrast, nested 
dictionaries provide a much more flexible and efficient solution. 

Indeed, there is a shortcut for getting a value out of a nested dictionary since 
the aict get command actually takes multiple keys as arguments, going along 
a path of nested dictionaries rather like a path name from a file system, like 
this: 


puts [dict get $employees 1234 firstname] 
=> Ann 


The handling of nested dictionaries (including how to efficiently update 
them) is discussed in more depth in Section 7.6. 

For comparison, here is an equivalent implementaton using arrays with 
structured keys, the most common method before Tcl 8.5: 
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set employees(0001,firstname) Joe 


( 

set employees (0001, surname) Schmoe 
set employees (0001,title) Mr 
set employees (1234,firstname) Ann 
set employees (1234,initial) E 
set employees (1234, surname) Huan 
set employees (1234,title) Miss 
puts Semployees (1234, firstname) 

= Ann 


That seems simpler right up until you want to get Ann’s records together, 
which is much easier, clearer, and quicker with dictionaries: 


# The dictionary version 
set AnnsRecords [dict get Semployees 1234] 
=> firstname Ann initial E surname Huan title Miss 
# The array version 
set AnnsRecords [array get employees 1234, *] 


7 > 


=> 1234,title Miss 1234,initial E 1234,surname Huan 1234, firstname Ann 


As the complexity of record processing increases, the filtering of the extra 
information from the element names can become seriously annoying. And 
because arrays are unordered, producing that output requires checking every 
element name in the whole array. 


7.3 Creating and Updating Dictionaries 


Tcl provides a command to help create dictionaries: aict create. This 
command ts the analog of 1ist (the constructor for lists); it takes an arbitrary 
number of key-value pairs and produces a dictionary with those key-value 
pairs init. When a key occurs multiple times, the value last associated with 
the key is used. This is useful in situations when you want to create a 
dictionary in which either the keys or the values are not fixed at the time you 
execute the command. 


dict create ab c{de} {fg} h a "b repeated" 
=>a {b repeated} c {d e} {f g} hc {d e} a {b repeated} {f g} h 


As you can see, the order of keys is the order in which they first appear in 
the list of arguments, but the value that is used is the last for a particular key 
in the sequence; earlier values for a duplicated key are dropped. This rule is 
applied when using aict replace to create a new dictionary based on the old 
one but with different values: 
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set example [dict create firstname Ann initial E \ 
surname Huan] 
=> firstname Ann initial E surname Huan 
dict replace S$example initial Y 
=> firstname Ann initial Y surname Huan 
dict replace S$example title Mrs surname Boddie 
= firstname Ann initial E surname Boddie title Mrs 


AS you Can See, aict replace can also add to the collection of keys. If instead 
you want to produce a dictionary with some keys removed, use the aict 
remove command. Note that removing a key that did not previously exist is not 
an error. 


dict remove $example initial 
=> firstname Ann surname Huan 

dict remove Sexample firstname title 
=> initial E surname Huan 


The aict merge command creates a new dictionary by merging two or more 
dictionaries, each provided as separate arguments. When two or more of the 
dictionaries have the same key, the resulting dictionary maps that key to the 
value according to the last dictionary on the command line containing a 
mapping for that key: 


set colorsl {foreground white background black} 
set colors2 {highlight red foreground green} 
dict merge $colorsl1 $colors2 

=> foreground green background black highlight red 


When you have a dictionary in a variable, you can update it directly to add 
keys, change what those keys map to, or remove keys. The first two 
operations are done with the aict set command, and the third operation is 
done with the aict unset command. The aict set command takes the name of 
the variable to update, the key to create or update, and the value that the key 
is to be set to and returns the resulting dictionary that it wrote back to the 
variable. The aict unset command takes the same arguments except for the 
value: 
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set example [dict create firstname Ann initial E \ 
surname Huan title Miss] 

=> firstname Ann initial E surname Huan title Miss 
dict set example title Mrs 

=> firstname Ann initial E surname Huan title Mrs 
dict get $example title 

=> Mrs 
dict set example surname Boddie 

= firstname Ann initial E surname Boddie title Mrs 
dict get Sexample surname 

=> Boddie 
dict unset example initial 

= firsname Ann surname Boddie title Mrs 
dict get $Sexample initial 

@ key "initial" not known in dictionary 


7.4 Examining Dictionaries: The size, exists, xeysy ANA tor 
Subcommands 


Once you have a dictionary, there are a number of operations you may 
perform to examine it. One of the simplest is determining the number of 
elements in the dictionary. This is done using the aict size command: 


dict size {firstname Ann surname Huan title Miss} 
a 
dict size {} 
=> 0 
set example {} 
dict set example a alpha 
dict set example b bravo 
dict set example c charlie 
dict set example d delta 
dict set example e epsilon 
dict size Sexample 
=>5 


You can check whether a particular key is in a dictionary with the aict exists 
subcommand. This returns 1 when the aict get command can be used on the 
same dictionary and key to retrieve a value successfully, and o when aict get 
will fail because the dictionary doesn’t contain the key: 
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set example {title Miss firstname Ann surname Huan} 
dict exists $example firstname 

=> 1 
dict exists $example initial 

=> 0 


To get a list of all the keys in the dictionary (in order), use the aict keys 
command. This command lists the keys of a dictionary value, optionally 
filtering them by a string matcn—Style pattern. Continuing with the previous 
example: 


dict keys $example 
=> title firstname surname 
dict keys $example {*name} 
=> firstname surname 


Similarly, the values from a dictionary can be retrieved in order using aict 
values, Which also takes an optional pattern: 


dict values Sexample 
= Miss Ann Huan 

dict values S$example *n* 
=> Ann Huan 


To loop over all the keys and values of a dictionary and execute some code 
for each of them, use the aict sor command. This takes an argument listing a 
pair of variables (one for the key and one for the value associated with that 
key), a dictionary, and a Tel script that forms the body of the loop. It returns 
the empty string. Just as with the foreach command, you can use break and 
continue to stop looping early or skip to the next key-value pair in the 
dictionary. 

For example, to print out the contents of a dictionary neatly: 


# Pretty print using the format command 
dict for {key value} $dict { 

puts [format "%s: ts" Skey $value] 
} 


# The result is empty, and the following lines are 
# printed to the console 

title: Miss 

firstname: Ann 

surname: Huan 


It is possible to produce a sorted dictionary by taking advantage of the fact 
that dictionaries preserve the order of their keys. You do this by creating a 
second dictionary from the first that has the keys in sorted order, and then 
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merging the values from the original dictionary with the aict merge 
subcommand: 


proc sortDict {dictionary} { 
set sorted {} 
foreach key [lsort [dict keys $dictionary]] { 
dict set sorted $key {} 
} 


return [dict merge $sorted $dictionary] 


} 


sortDict Sexample 
=> firstname Ann surname Huan title Miss 


7.5 Updating Dictionary Values 


Sometimes it is necessary to update the values in a dictionary by changing 
them based on their current values rather than just replacing them with new 
ones. The aict command provides a number of convenience subcommands 
(based on other Tcl commands) to make this easier, so there is no need to 
get the value out of the dictionary into a variable, update the value in the 
variable, and then write that value back. 

The easiest way to append a string or strings to a value in a dictionary is to 
use the aict appena Subcommand. This takes the name of a variable holding 
the dictionary you want to update, the key whose value you want to update, 
and one or more strings to append to the value and returns the updated 
dictionary as well as writing it back to the variable: 


set example {firstname Ann surname Huan title Miss} 
dict append example firstname ie 
=> firstname Annie surname Huan title Miss 


Similarly, when you want to build up a list in a dictionary value, you can 
use the aict 1appena SUbcommand: 


set shopping {fruit apple veg carrot} 
dict lappend shopping fruit orange 
=> fruit {apple orange} veg carrot 
dict lappend shopping fruit banana 
=> fruit {apple orange banana} veg carrot 
dict lappend shopping veg cabbage beans 
= fruit {apple orange banana} veg {carrot cabbage beans} 
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Another updating operation supported by the aict command 1s aict incr. This 
takes a variable containing a dictionary, a key whose value will be 
incremented, and an optional value by which to increment the value. The 
result of the command is the updated dictionary, which is also written back 
to the variable. Analogously to the variable passed to the normal incr 
command (in Tcl 8.5 and later), the key does not have to exist previously in 
the dictionary, as it is assumed to have a value of o if absent. This is 
particularly useful when computing things like frequency histograms of 
words within a piece of text. An example is this procedure: 


proc computeHistogram {text} { 
set frequencies {} 
foreach word [split $text] { 
# Ignore empty words caused by double spaces 
if {$word eq ""} continue 
dict incr frequencies [string tolower $word] 


return $frequencies 


} 
computeHistogram "this day is a happy happy day” 
=> this 1 day 2 is 1 al happy 2 


Obviously, the aict command cannot supply a command for every kind of 
complex update that anyone might want to do. Instead, it supplies a general 
command for temporarily associating variables with selected keys of a 
dictionary, which you can use to build any kind of updating scheme at all. 
This is done using the aict update subcommand, which takes the name of a 
variable containing a dictionary, a list of keys in the dictionary and 
variables to associate with them, and a Tcl script that describes an 
operation that updates those variables. The result of the script is also the 
result of the overall aict upaate command. Upon completion of the script, the 
state of the variables is written back into the dictionary, thus allowing for 
arbitrarily complex updates of the dictionary. 


Note 


If a named key does not exist in the dictionary at the start of the aict 
update Command, its corresponding variable is unset at the start of 
execution of the body script. At the end of the script, named keys that 
do not have their variables set are removed from the modified 
dictionary; that is, nonexistence of keys corresponds to nonexistence of 
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variables. 


Many different kinds of updates are possible using this mechanism. For 
example, here is how to reimplement the aict unset command: 


dict update aDictionaryVariable $theKey localvar { 
unset localVar 


More complex updates are also possible. Here is an example that switches 
the values between two keys: 


set example {firstname Ann surname Huan title Miss} 
dict update example firstname vl surname v2 { 
lassign [list $vl $v2] v2 vl 


} 


puts Sexample 
=> firstname Huan surname Ann title Miss 


This example shows how to make a square-a-value operation: 


proc squareValue {dictVar key} { 
upvar 1 $dictVar d 
dict update d $key v { 
set v [expr {$v ** 2}] 
} 
} 


set polyFactors {C 1 x 2 y 3} 
squareValue polyFactors y 
Bie. Lx 2 y-3 


One tricky feature is that updates to the variable containing the dictionary 
happen only when the body of the aict upaate command finishes, and the key- 
value pairs not mapped by this subcommand are left untouched. This makes 
the behavior of the system much easier to understand when a complex 
update is being performed: 
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set example {firstname Ann surname Huan title Miss} 
=> firstname Ann surname Huan title Miss 
set i "a dummy value" 
dict update example surname s notes n initial i { 
dict set example title Mrs 
unset s 
set n "have initial = [info exists i]" 
# Print the current contents of the dictionary 
puts $example 
} 
=> firstname Ann surname Huan title Mrs 
# Get the contents of the variable after the dict 
update command has completed; note it is different 
in several respects, but the value for 'title' is 
unchanged because that key was not listed at the 
# start of the command. 
puts Sexample 
=> firstname Ann title Mrs notes fhave initial = 0} 


3& tr 4b 


Note that although the ; variable was removed during the body of the aict 
update, it was not until after the command had finished that the alterations 
were reincorporated back into the dictionary and the key surname was 
removed. Similarly, the key initia: did not exist in the dictionary at the start 
and so the variable i was unset. 


7.6 Working with Nested Dictionaries 


Many of the aict subcommands have extra support for working with nested 
dictionaries. This allows you to specify multiple keys to the command and 
have the command go through the nested dictionaries to the point specified 
and work there, rather like a directory path name in a file system. The 
subcommands that support this method of working are aict get, dict exists, 
dict set, dict unset, and dict with. 

The aict get command has the simplest nested dictionary behavior. When 
you ask for a value from a nested dictionary, it just goes through the nested 
dictionaries in order, using earlier keys to select the dictionaries where the 
later keys may be found. Thus, the command 


dict get $dictionary keyOne keyTwo 
is exactly the same as 


dict get [dict get $dictionary keyOne] keyTwo 
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The aict exists command corresponds to the preceding line. It checks for the 
existence of all the keys along the path, and that all the steps along the path 
through the nested dictionaries are themselves dictionaries; it is an error if 
they exist but are not dictionaries. Thus, the following two commands are 
equivalent: 


dict exists $dictionary keyOne keyTwo 
expr { 
[dict exists $dictionary keyOne] && 
[dict exists [dict get $dictionary keyOne] keyTwo] 


As you can see, the multikey versions of both aict get and aict exists are 
much simpler to use when you have nested dictionaries. 

The nested versions of the aict set and aict unset commands have even more 
complex equivalences to simple aict usage, enough that they are not 
described here in code. It 1s worth noting that the aict set command will 
create dictionaries along the path if necessary, though aict unset will only 
delete the key from the innermost dictionary on the path of keys; it does not 
delete the dictionaries forming the structure of the path, even if those 
dictionaries become empty. 


set nestedDict {firstname Ann surname Huan} 

= firstname Ann surname Huan 
dict set nestedDict address street {Ordinary Way} 

=> firstname Ann surname Huan address {street {Ordinary Way}} 
dict set nestedDict address city Springfield 

=> firstname Ann surname Huan address {street {Ordinary Way} city 
Springfield} 
dict get $nestedDict address street 

=> Ordinary Way 
dict unset nestedDict address street 

= firstname Add surname Huan address {city Springfield} 


The other command designed for working with nested dictionaries is the aict 
with Subcommand. This allows the “opening out” of a dictionary into 
variables in a manner similar to the aict upaate command, but with a few 
differences. Instead of giving you control over which keys to work with and 
what variables they are to be bound to, aict witn allows the selected 
dictionary or any subdictionary (as specified by the path of keys) to open 
out in its entirety. 
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set example { 
A { 
alphabet {a alpha b bravo c charlie} 
animals {cow calf sheep lamb pig ? goose ?} 


c { 
comedians {laurel&hardy morecambe&wise} 
} 
} 


dict with example c { 
puts “comedians: $comedians" 
lappend comedians "steve martin" 


} 


=> comedians: laurel&hardy morecambe&wise 
=> laurel&hardy morecambe&wise {steve martin} 
dict with example A alphabet { 
puts "NATO ABC: $a $b $c" 
} 


= NATO ABC: alpha bravo charlie 
dict with example A animals { 
set pig piglet 
set goose gosling 


} 


dict with example A { 
dict for {k v} Sanimals { 
puts "$k has baby $v" 
} 
} 


=> cow has baby calf 

=> sheep has baby lamb 

=> pig has baby piglet 

=> goose has baby gosling 


The aict with command can be used to allow the stowing of some persistent 
procedure state in a global variable without polluting the global namespace 
with lots of different variables or requiring every use of the global state to 
be encapsulated within array syntax, which is the other solution. The use of 
this is illustrated within the stepcounter procedure in this example: 
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set counters { 
next 0 
} 


proc makeCounter {{step 1} {offset 0}} { 
global counters 
set id counter[dict get $counters next] 
dict incr counters next 
dict set counters $id [dict create \ 
state 0 step $step offset Soffset]) 
return $id 
} 
proc stepCounter {id} { 
global counters 
dict with counters $id { 
return [expr {[incr state $step] + $offset}] 
} 


} 


When used, this makes for a very simple stateful counter system that can 
count in steps of any size desired with an arbitrary offset applied at each 
stage, and all at a cost of exactly one global variable. A sample of this 
simple-to-extend mechanism is shown below, where two counters are first 
created and then used in an interleaved fashion: 


set a [makeCounter] 
=> counterd 
set b [makeCounter 5 -4] 
=> counter! 
stepCounter $a 
— oe 
stepCounter $a 
=a 
stepCounter $b 
=> 1 
stepCounter $a 
=>3 
stepCounter $b 
>6 
stepCounter $a 
=f 
stepCounter $b 
= 22 
puts Scounters 
= next 2 counter0 {step 1 state 4 offset 0} counterl {step 5 state 
15 offset -4} 


Another key usage of dictionaries and the aict witn subcommand is for 
representing the results of a database query. Each column from the row of 
results can be given a unique name (e.g., the name of the table column) with 


the contents of that column being the dictionary value!, and the iteration 
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order of the dictionary being the order of the columns. For well-behaved 
query results (1.e., almost all) the dictionary is then trivial to map into 
variables using aict with. 


1. Null columns are best represented as absent keys, since the nuxz value 
actually represents an absence ofa value for a particular column in that row. 
Of course, a database interface might also provide other options for 
handling Nulls in particular columns (e.g., particular strings). This is all 
outside the scope of dictionaries, though. They provide mechanisms; they do 
not define interface policy. 


set result [dbConn query { 
SELECT firstname, surname, title FROM staff 
LIMIT 2 
}] 
=> {firstname Joe surname Schmoe title Mr} {firstname Annie surname 
Huan title Miss} 
foreach row $result { 
dict with row { 
puts "found $title $firstname $surname" 
} 


} 


= found Mr Joe Schmoe 
= found Miss Annie Huan 
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8. Control Flow 


This chapter describes the Tcl commands for controlling the flow of 
execution ina script. Tcl’s control flow commands are similar to the control 
flow statements in the C programming language and the Unix shell csn, 
including it, white, for, foreach, switch, and eval. 


8.1 Commands Presented in This Chapter 


You can use the following commands to control the flow of execution in a 
Tel script: 

® break 
Terminates the innermost nested looping command. 


* continue 


Terminates the current iteration of the innermost looping command and goes 
on to the next iteration of that command. 


® eval arg ?arg arg...? 


Concatenates all of the args with separator spaces, then evaluates the result 
as a Tcl script and returns its result. 

® for init test reinit body 
Executes init as a Tel script, then evaluates tes: as an expression. If it 
evaluates to true, it executes pboay as a Tel script, executes reinit as a Tel 
script, and reevaluates test as an expression. Repeats until test evaluates to 
false. Returns an empty string. 

® foreach varName list body 

foreach varlistl listl1 ?varlist2 list2 ...? body 

For each element of 1:s+, in order, sets the variable varwame to that value and 
executes poay aS a Tcl script. Returns an empty string. 1is: must be a valid 
Tel list. In the general case, foreach can iterate over multiple lists as well as 
process multiple elements from a list in each iteration. 

° if testl bodyl ?elseif test2 body2 elseif ...? ?else bodyn? 
Evaluates testi as an expression. If its value is true, it executes poay1 as a Tcl 
script and returns its value. Otherwise it evaluates test2 aS an expression; if 
its value is true, it executes poay2 as a Script and returns its value. If no test 
succeeds, it executes boayn as a Tcl script and returns its result. 


® source ?-encoding encodingName? fileName 
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Reads the file whose name 1s fiiewame and evaluates its contents as a Tcl 
script. Returns the result of the script. Tcl reads the file using the operating 
system’s default character set encoding unless you provide the -encoding 
option. 

® switch ?options? string {pattern body ?pattern body ...?} 
switch ?options? string pattern body ?pattern body ...? 
Matches string against each pattern in order until a match is found, then 
executes the poay corresponding to the matching pattern. If the last pattern 18 
default, 1t matches anything. Returns the result of the oay executed, or an 
empty string if no pattern matches. options May be -exact, -glob, -regexp, OF -- tO 
indicate the end of options. When using -regexp matching, -matchvar and - 
indexvar can be used to access matching regular expression subpatterns. 

® while test body 
Evaluates test aS an expression. If its value is true, it executes poay as a Tel 
script and reevaluates test. Repeats until test evaluates to false. Returns an 


empty string. 


8.2 The :« Command 


The ic command evaluates an expression, tests its result, and conditionally 
executes a script based on the result. For example, consider the following 
command, which sets variable « to o if it was previously negative: 


if {$x <0} { 
set x 0 


} 


In this case it receives two arguments. The first is an expression and the 
second is a Tcl script. The expression can have any of the forms for 
expressions described in Chapter 4. The is command evaluates the 
expression and tests the result; if it is true, ic evaluates the Tcl script. If the 
value is false, ic returns without taking any further action. 

if commands can also include one or more eiseis clauses with additional 
tests and scripts, plus a final cise clause with a script to evaluate if no test 
succeeds: 
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if {$x < 0} { 


\ elseif {$x == 0} { 
Y pihsedé {Ga-u= 2} f 
Y elke | 


} 


This command will execute one of the four scripts indicated by ..., 
depending on the value of x. The result of the command will be the result of 
whichever script is executed. If an ic command has no «cise clause and none 
of its tests succeeds, it executes no script and returns an empty string. 
Remember that the expressions and scripts for is and other control structures 
are parsed using the same approach as all arguments to all Tcl commands. It 
is almost always a good idea to enclose the expressions and scripts in 
braces so that substitutions are deferred until the command is executed. 
Furthermore, each open brace must be on the same line as the preceding 
word or else the newline will be treated as a command separator. The 
following script is parsed as two commands, which results in an error as 
there are not enough arguments for the is command: 


if {Sx <0} 
{ 


set x 0 


} 


8.3 The svitn Command 


The switch command tests a value against a number of patterns and executes 
one of several Tcl scripts depending on which pattern matches. The same 
effect as switch can be achieved with an is command that has lots of eciseis 
clauses, but switch provides a more compact way of expressing the structure. 
Tel’s switch command has two forms; here is an example of the first: 


switch $x {a {incr tl} b {incr t2} c {incr t3}} 


The first argument to switch is the value to be tested (the contents of variable 
x In the example). The second argument is a list containing one or more 
pairs of elements. The first argument in each pair is a pattern to compare 
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against the value, and the second 1s a script to execute if the pattern matches. 
The switch command steps through these pairs in order, comparing the pattern 
against the value. As soon as it finds a match, it executes the corresponding 
script and returns the value of that script as its value. If no pattern matches, 
no script is executed and switch returns an empty string. This particular 
command increments variable +: if x has the value a, +2 if x has the value » or 
3 1f x has the value - and does nothing otherwise. 

The second form spreads out the patterns and scripts into separate 
arguments rather than combining them all into one list: 


switch $x a {incr tl} b {incr t2} ¢ {incr t3} 


This form has the advantage that you can invoke substitutions on the pattern 
arguments more easily, but most people prefer the first form because you 
can easily spread the patterns and scripts across multiple lines like this: 


switch $x { 
a {incr t1} 
b {incr t2} 
ec {incr t3} 


} 


The outer braces keep the newlines from being treated as command 
separators. With the second form you would have to use backslash-newlines 
like this: 


switch $x \ 
a {iner ti} \ 
b {incr t2} \ 
c {incr t3} 


The switch command supports three forms of pattern matching. You can 
precede the value to test with a switch that selects the form you want: -exact 
selects exact string comparison, -gio» selects pattern matching as in the string 
match Command (see Section 5.10 for details), and -regexp selects regular 
expression matching as described in Section 5.11. The default behavior is - 
exact. 

For regular expression matching, you can also provide a -matchvar argument 
followed by a variable name. The switcn command stores a list in the 
variable where the first element is the string that matches the entire regular 
expression, the second element consists of the characters that match the first 
capturing subpattern, and so on. If the regular expression matches no 
characters, the value of the match variable is an empty list. The -indexvar 
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option is similar to -matchvar, but instead of the actual characters matched, 
the index variable specified receives a list of character indices referring to 
the matching substrings. The first element of the index variable is a two- 
element sublist specifying the indices within the test string of the first and 
last characters matching the regular expression; the second element is a 
sublist specifying the indices of the characters matching the first capturing 
subpattern; and so on. 


Note 


If the test value starts with a - character, the switch command can 
mistake it for an option, causing an error. In general, you should always 
use the -- option to mark the end of options and ensure that switch 
correctly identifies the test string in all circumstances. 


If the last pattern in a switcn command 1s cefauit, 1t matches any value; thus 
switch executes the aefauit script if no other patterns match. For example, the 
following script examines a list and produces three counters. The first, «1, 
counts the number of elements in the list that contain an a. The second, +2, 
counts the number of elements that are unsigned decimal integers. The third, 
+3, counts all of the other elements: 


set tl 0 

set t2 0 

set t3 0 

foreach i $x { 

switch -regexp -- $i { 

a {incr t1} 
“[0-9]4$ {incr t2} 
default {incr t3} 


} 


If a script in a switch command is -, switcn uses the script for the next pattern 
instead. This makes it easy to have several patterns that execute the same 
script, as in the following example: 


switch -- $x { 
a - 
— 
ec {incr t1} 
d {incr t2} 
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This script increments variable +1 if x 1S a, », Or c, and it increments 2 if x is 
d. 


Note 


A common error for newcomers to Tcl is improper placement of 
comments in a switch Statement. You can place a comment only where 
the Tcl interpreter expects to find a Tcl command. In a switcn statement, 
that means that you must place comments inside the scripts: 


switch -- $x { 
# This comment will cause an error 
abe {...} 
} 
switch -- $x { 
abe { 
# This comment is okay 


8.4 Looping Commands: waite, sory ANA foreach 


Tcl provides three commands for looping: white, for, and foreach. Each of 
these commands executes a script over and over again; they differ in the 
kinds of setup they do before each iteration and in the ways they decide to 
terminate the loop. 

The wniie command takes two arguments: an expression and a Tcl script. It 
evaluates the expression and if the result is nonzero, it executes the Tcl 
script. This process repeats over and over until the expression evaluates to 
false, at which point the wni1e command terminates and returns an empty 
string. For example, the following script copies a list from variable a to 
variable », reversing the order of the elements along the way: 
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set b {} 
set i [expr {[llength $a] - 1}] 
while {$i >= 0} { 
lappend b [lindex $a $i] 
Wal os opie Rape S 


} 


The sor command is similar to wniie except that it provides more explicit 
loop control. The program to reverse the elements of a list can be rewritten 
using for as follows: 


set b {} 

for {set i [expr {[llength $a] - 1}]} {$i >= 0} {iner i -1} { 
lappend b [lindex $a $i] 

} 


The first argument to sor is an initialization script; the second is an 
expression that determines when to terminate the loop; the third is a re- 
initialization script, which is evaluated after each execution of the loop 
body before the test is evaluated again; and the fourth argument is a script 
that forms the body of the loop. for executes its first argument (the 
initialization script) as a Tcl command, then evaluates the expression. If the 
expression evaluates to true, ror executes the body followed by the re- 
initialization script and reevaluates the expression. It repeats this sequence 
over and over again until the expression evaluates to false. If the expression 
evaluates to false on the first test, neither the body script nor the re- 
initialization script is executed. Like wniie, ror returns an empty string as the 
result. 

for and while are equivalent in that anything you can write using one 
command you can also write using the other command. However, for has the 
advantage of placing all of the loop control information in one place where 
it is easy to see. Of course, 1n some situations the loop initialization or re- 
initializaion either is more complex or is nonexistent, and in these cases a 
while loop may make more sense. 

The foreach command iterates over all of the elements of a list. For example, 
the following script provides yet another implementation of list reversal: 


set b {} 
foreach i $a { 

set b [linsert $b 0 $i] 
} 


The simplest form of foreach takes three arguments. The first is the name of a 
variable, the second is a list, and the third is a Tcl script that forms the body 
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of the loop. foreach executes the body script once for each element of the list, 
in order. Before executing the body in each iteration, ¢oreach sets the variable 
to hold the next element of the list. Thus, if variable « has the value first 
second third In the preceding example, the body is executed three times. In the 
first iteration i has the value first, in the second iteration it has the value 
second, and in the third iteration it has the value tnira. At the end of the loop, » 
has the value thira secona first and i has the value tnira. As with the other 
looping commands, foreach always returns an empty string. 

In addition to a single variable name, the foreacn command can accept a list 
of variable names. In this case, each iteration of the loop assigns 
consecutive element values to the corresponding variable names, so if you 
provide three variable names, foreacn processes the list three elements at a 
time. The loop iterates until all elements have been used; if a value list 
doesn’t contain enough elements for each loop variable on the last iteration, 
empty strings are used for the missing elements: 


foreach {x y} {abcde} { 
puts "<$x> <$y>" 
} 


=> <a> <b> 
<c> <d> 


<e> <> 


The foreach command also can process multiple lists in parallel, with a 
separate set of variables for each list: 
foreach i {a b} {j k} {vwxy z} { 
pute "f:<Sio; P<Sis; ke<Sk>" 
<b>, J3:<x>, K:<y> 


=> i:<a>, j:<v>, k:<w> 
i: 
i: 


Ky Jt<Zoy, kr<> 
8.5 Loop Control: vreax ANA continue 


Tcl provides two commands that can be used to abort part or all of a 
looping command: wreak and continue. These commands have the same 
behavior as the corresponding statements in C. Neither takes any arguments. 
The break command causes the innermost enclosing looping command to 
terminate immediately. For example, suppose that in the list reversal 
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example in the preceding section we want to stop as soon as an element 
equal to 222 is found in the source list. In other words, the result list should 
consist of a reversal of only those source elements up to (but not including) 
a zzz element. This can be accomplished with break as follows: 


set b {} 

foreach i $a { 
if {$i == "222"} break 
set b [linsert $b 0 $i] 


} 


The continue command causes only the current iteration of the innermost loop 
to be terminated; the loop continues with its next iteration. In the case of 
while, this means skipping out of the body and reevaluating the expression 
that determines when the loop terminates; in sor loops, the re-initialization 
script 1s executed before the termination condition is reevaluated. For 
example, the following program is another variant of the list reversal 
example, where zzz elements are simply skipped without being copied to the 
result list: 


set b {} 

foreach i $a { 
if {$i == "ZZZ"} continue 
set b [linsert $b 0 $1] 


8.6 The «2. Command 


eval 18 a general-purpose building block for creating and executing Tcl 
scripts. It accepts any number of arguments, concatenates them with 
separator spaces, and then executes the result as a Tcl script. All Tcl parsing 
rules apply to the script, so the script can contain multiple commands, span 
multiple lines, include comments, and so on. 

One use of eva: 1s for generating commands, saving them in variables, and 
then later evaluating the variables as Tcl scripts. For example, the script 
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set reset { 
set a 0 
set b 0 
set c 0 


} 
eval $reset 


clears variables a, », and - to o when the eva1 command is invoked. In this 
case, there is no advantage to assigning the script to a variable only to 
execute it with evai; it makes much more sense to execute the three set 
commands directly. But if you are writing an application in which the script 
is created as a result of dynamic processing, eval is an appropriate way to 
execute the script. 

Historically the most important use for evai has been to force another level 
of parsing. The Tcl parser performs only one level of parsing and 
substitution when parsing a command; the results of one substitution are not 
reparsed for other substitutions. However, there are times when another 
level of parsing is necessary, and evai provides the mechanism to achieve 
this. 

Most commonly, this situation arises when you have a list of values, stored 
in either a variable or the return value of a command, and you need to pass 
the list to a command as separate values. For example, suppose that a 
variable vars contains a list of variables and that you wish to unset each of 
these variables. One solution is to use the following script: 


set vars {a bc d} 
foreach i $vars { 


unset Si 
} 


} 


This script works just fine, but the unset command takes any number of 
arguments so it should be possible to unset all of the variables with a single 
command. Unfortunately the following script does not work: 


set vars {a bc d} 
unset $vars 


The problem with this script is that all of the variable names are passed to 
unset aS a Single argument, instead of there being a separate argument for 
each name. Thus unset tries to unset a variable named a » c a. 

As of Tcl 8.5, the preferred solution is to use the ;«} syntax for argument 
expansion, as described in Section 2.8: 
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set vars {a bc d} 
unset {*}$vars 


Prior to Tcl 8.5, the only solution was to use evai, as with the following 
command: 


set vars {a bc d} 
eval unset $vars 


eval Concatenates its arguments to forma new command unset a » ¢ a, Which 
it then passes to Tcl for evaluation. The command string gets reparsed, so 
each variable name ends up ina different argument to unset. 


Note 


As long as the variable names in this example are provided in a well- 
formed Tel list with only space and tab characters as element 
delimiters, this approach works even if some of the variable names 
contain spaces or special characters such as s. The command 


eval unset $vars 
is identical to the command 
eval [concat unset $vars] 


In either case, the script evaluated by evai is a proper list whose first 
element 1S unset and whose other elements are the elements of vars. 


8.7 Executing from Files: source 


The source command reads a file and executes the contents of the file as a Tcl 
Script. source takes a single argument that specifies the name of the file. For 
example, the command 


source init.tcl 


executes the contents of the file init.tci. You can specify the file using either 
an absolute path or a path relative to the present working directory of the 
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script currently executing. 

The return value from source 1s the value returned when the file contents are 
executed, which is the return value from the last command in the file. In 
addition, source allows the return command to be used in the file’s script to 
terminate the processing of the file. See Section 9.2 for more information on 
return. 

Using the source command, you can break a large script into smaller 
modules, and then have one main script source the other script modules. You 
can create libraries of reusable procedures by placing the procedure 
definitions in a file that you can source from multiple applications. For 
information on creating more elaborate script libraries, see Chapter 14. 
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9. Procedures 


A Tel procedure is a command that you define with a Tcl script. You can 
define new procedures at any time with the proc command described in this 
chapter. Procedures make it easy for you to package solutions to problems 
so that they can be reused easily. 

Tcl also provides special commands for dealing with variable scopes. 
Among other things, these commands allow you to pass arguments by 
reference instead of by value and to implement new Tcl control structures as 
procedures. 


9.1 Commands Presented in This Chapter 


The following Tcl commands relate to procedures and variable scoping: 

® proc name argList body 
Defines a procedure whose name is name, replacing any existing command by 
that name. argzist 18 a list with one element for each of the procedure’s 
arguments, and poay contains a Tcl script that is the procedure’s body. 
Returns an empty string. 

* apply fargList body ?namespace?} ?argl arg2...? 
Applies the anonymous procedure to the arguments and returns the result. 
The procedure definition consists of a two- or three-element list. The argzist 
and boay elements are specified as with proc. The optional namespace element 
specifies a namespace in which to evaluate the procedure. 

® return ?options? ?value? 
Returns from the innermost nested procedure or source command with vaiue 
as the result of the procedure. vaiue defaults to an empty string. Additional 
options may be used to trigger an exceptional return (see Section 13.5). 

® global namel ?name2 ...? 
Binds variable names namei, name2, etc. to global variables. References to 
these names will refer to global variables instead of local variables for the 
duration of the current procedure. Returns an empty string. 

* upvar ?level? otherVarl myVarl ?otherVar2 myVar2 ...? 
Binds the local variable named myvari to the variable at stack level tevei 
whose name 1S othervari1. For the duration of the current procedure, variable 


references to myvar1 will be directed to ctnervar1 instead. Additional bindings 
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may be specified with ctnervar2 and myvar2, etc. ievei has the same syntax and 
meaning as upievei and defaults to 1. Returns an empty string. 

® uplevel ?level? arg ?arg arg...? 
Concatenates all of the args with spaces as separators, then executes the 
resulting Tcl script in the variable context of stack level 1eve1. 1ever consists 
of a number or a number preceded by + and defaults to i. Returns the result 


of the script. 


9.2 Procedure Basics: proc ANA return 


Procedures are created with the proc command, as in the following example: 
proc plus {a b} { expr {$at+$b} } 


The first argument to proc 1s the name of the procedure to create, pius in this 
case. The second argument is a list of names of arguments to the procedure 
(2 and » in the example). The third argument to proc 1s a Tcl script that forms 
the body of the new procedure. After the proc command completes, a new 
command, pius, exists, which can be invoked just like any other Tcl 
command. When pius is invoked, Tcl arranges for the procedure’s body to be 
evaluated with the variables « and » set to the values of the arguments. pius 
must always be invoked with exactly two arguments; the Tcl interpreter 
raises an error if you invoke a procedure with the wrong number of 
arguments. The return value for the pius command is the value returned by 
the last command in pius’s body. Here are some correct and incorrect 
invocations of p1us: 


plus 3 4 
plus 3 -l 
> 2 
plus 1 
@ wrong # args: should be “plus a b" 


It is important to realize that proc is just an ordinary Tcl command. It is not a 
declaration with special syntax, as you might see in other languages such as 
C. The arguments to proc are processed in the same way as for any other Tcl 
command. For example, the braces in the argument (2 »; are not a special 
syntactic construct for this command; they are used in the normal fashion to 
pass both of pius’s argument names to proc as a Single list of argument names. 
Technically, if a procedure has only a single argument, the braces aren’t 
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needed around its name, though most Tcl programmers still use them for 
consistency. Similarly, the braces around proc’s last argument are used to 
pass the entire script body to proc as a single argument without performing 
substitutions on its contents. 

If you would like a procedure to return early without executing its entire 
script, you can invoke the return command: it causes the enclosing procedure 
to return immediately, and the argument to return is the result of the 
procedure. Here is an implementation of a factorial function that uses return: 


proc fac {x} { 
tf (6x <a 1}. { 
return 1 
} 


return [expr {$x * [fac [expr {$x-1}]]}] 


} 


fac 4 
=> 24 
fac 0 


> J 


If the argument to sac is less than or equal to 1, fac invokes return to return 
immediately. Otherwise fac executes the exp: command, which recursively 
calls sac and returns the result. 


Note 


In this example you could invoke the expr command without the 
“enclosing” return command. The exe: command would be the last 
command in the procedure’s body, so its result would be returned as 
the result of the procedure. However, using the return command in 
cases like this makes your intention clear to programmers maintaining 
your code, so it is less likely that someone will add commands to the 
end of the procedure definition and inadvertently change its behavior. 


9.3 Local and Global Variables 


When the body of a Tcl procedure is evaluated, it uses a different set of 
variables from its caller. These variables are called /ocal variables, since 
they are accessible only within the procedure and are deleted when the 


208 


procedure returns. Variables defined outside of a procedure are called 
global variables. Global variables are persistent, existing until explicitly 
deleted. Tcl also supports namespace variables, which are persistent 
variables existing in the context of a particular namespace. Chapter 10 
discusses namespaces and the use of namespace variables. It is possible to 
have a local variable with the same name as a global variable, namespace 
variable, or a local variable in another active procedure, but these are 
different variables: changes to one do not affect any of the others. If a 
procedure is invoked recursively, each recursive invocation has a distinct 
set of local variables. 

The arguments to a procedure are just local variables whose values are set 
from the words of the command that invoked the procedure. When execution 
begins in a procedure, the only local variables with values are those 
corresponding to the arguments passed to the procedure. Other local 
variables are created automatically when they are set. 

A procedure can reference global variables with the gicba1 command. For 
example, the following command makes the global variables « and y 
accessible inside a procedure: 


global x y 


The gioba1 command treats each of its arguments as the name of a global 
variable and arranges for references to those names within the procedure to 
be directed to global variables instead of local ones. gicbai can be invoked 
at any time during a procedure; once it has been invoked, it remains in effect 
until the procedure returns. 


Note 


Tcl does not provide a form of variables equivalent to static variables 
in C, which are limited in scope to a given procedure but have values 
that persist across calls to the procedure. In Tcl you must use global or 
namespace variables for purposes like this. In general, you should 
prefer using namespace variables to avoid name conflicts with other 
such variables. 


9.4 Defaults and Variable Numbers of Arguments 
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In the examples so far, the second argument to proc (which describes the 
arguments to the procedure) has taken a simple form consisting of the names 
of the arguments. Three additional features are available for specifying 
arguments. First, the argument list may be specified as an empty string. In 
this case the procedure takes no arguments, and trying to invoke it with 
arguments results in an error. For example, the following command defines 
a procedure that prints out two global variables: 


proc printVars {} { 
global a b 
puts "a is $a, b is $b" 


} 


The second additional feature is that defaults may be specified for some or 
all of the arguments. The argument list is actually a list of lists, in which 
each sublist corresponds to a single argument. If a sublist has only a single 
element (which has been the case in the previous examples), that element is 
the name of the argument. If a sublist has two arguments, the first is the 
argument’s name and the second is a default value for it. For example, here 
is a procedure that increments a given value by a given amount, where the 
amount defaults to 1: 


proc inc {value {increment 1}} { 
expr $value+$increment 
} 


The first element in the argument list, vaiue, specifies a name with no default 
value. The second element specifies an argument with the name increment and 
a default value of :. This means that inc can be invoked with either one or 
two arguments: 


inc 42 3 
=> 45 

inc 42 
=> 43 


Ifa default isn’t specified for an argument in the proc command, the argument 
must be supplied whenever the procedure is invoked. The defaulted 
arguments, if any, must be the last arguments for the procedure. This is true 
both in the proc command and when invoking a procedure. If a default is 
specified for a particular argument, defaults must be provided for all the 
arguments following that one; similarly, if an argument is omitted when the 
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procedure is invoked, all the arguments after it must also be omitted. 

The third special feature in argument lists is support for variable numbers of 
arguments. If the last argument in the argument list has the special name arss, 
the procedure may be called with varying numbers of arguments. Arguments 
before args in the argument list are handled as before, but any number of 
additional arguments may be specified. The procedure’s local variable args 
is set to a list whose elements are all of the extra arguments. If there are no 
extra arguments, args is set to an empty string. For example, the following 
procedure takes any number of arguments and returns their sum: 


proc sum {args} { 
set total 0 
foreach val Sargs { 
set total [expr {$total + $val}] 
} 


return Stotal 


} 


Sun.s. 2 2:4 $ 
| — Oe 

sum 
= 0 


If a procedure’s argument list contains additional arguments before args, they 
may be defaulted as just described. No default value may be specified for 
args—the empty string is its default. 


9.5 Call by Reference: wva: 


Tcl supports call-by-value argument passing only. When you invoke a Tcl 
command, copies of the argument values are passed to the command. This is 
true even if the value came from a variable, because the Tcl interpreter 
substitutes the value of the variable before executing the command. Thus, in 
the following example, all the sum command receives are copies of the 
values that are stored in the a and » variables: 


sum $a $b 


Tcl does not support true pointer or reference types, either, so it would seem 
at first impossible to write a procedure that could modify the value of an 
existing variable. However, the name of a variable is simply a string value, 
which can in turn be stored in another variable. Therefore, by requesting 
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additional rounds of substitution, we can emulate the behavior of a 
reference, like so: 


set x "The value of x" 
set y x ;# This stores the single character "x" in y 
set Sy 

=> The value of x 


In this example, the Tcl interpreter substitutes sy with its string value, «. The 
set command then executes, interprets its argument as the name of a variable, 
and returns the value stored in the variable. This concept, in combination 
with a Tcl command called upvar, allows us to implement the equivalent of 
call-by-reference behavior. 

The upvar command provides a general mechanism for accessing variables 
outside the context of a procedure. It can be used to access global variables, 
namespace variables, or local variables in some other active procedure. 
Most often it is used to implement the equivalent of call-by-reference 
argument passing, which is particularly useful for arrays. If ais an array, you 
cannot pass it to a procedure myproc with a command like myproc sa, because 
there is no value for an array as a whole; there are values only for the 
individual elements. Instead, you can pass the name of the array to the 
procedure, as iN myproc a, and use the upvar command to access the array’s 
elements from the procedure. 

Here is a simple example of upvar in a procedure that prints out the contents 
of an array: 


proc printArray {name} { 
upvar $name a 
foreach el [lsort [array names a]] { 
puts "Sel = Sa($el)" 
} 


} 
set info(age) 37 
set info(position) "Vice President" 
printArray info 
=> age = 37 
position = Vice President 


When printarray 18 invoked, it is given the name of an array as an argument. 
The upvar command then makes this array accessible through the local 
variable 2 in the procedure. The first argument to upvar 1s the name of a 
variable accessible to the procedure’s caller. This may be a global variable, 
as in the example, a namespace variable, or a local variable in a calling 
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procedure. The second argument is the name of a local variable. upvar 
arranges things so that accesses to the local variable @ actually refer to the 
variable in the caller whose name is given by the variable name. In the 
example this means that when printarray reads elements of a, it is actually 
reading elements of the inso global variable. If printarray were to write a, it 
would modify info. printarray USeS the array names Command to retrieve a list 
of all the elements in the array. Then it sorts them with isort and prints each 
of the elements in order. 


Note 


In the example it appears as if the output is returned as the procedure’s 
result; in fact, it is printed by the procedure directly to standard output, 
and the result of the procedure is an empty string. 


The first variable name in an upvar command by default refers to the context 
of the current procedure’s caller. However, it is also possible to access 
variables from any level on the call stack, including the global level. For 
example, 


upvar #0 other x 


makes the global variable ctner accessible via the local variable « (the +o 
argument specifies that other should be interpreted as a global variable, 
regardless of how many nested procedure calls are active), and 


upvar 2 other x 


makes the variable otner in the caller of the caller of the current procedure 
accessible as the local variable « (2 specifies that the context of otner is two 
levels up the call stack). The level o (as opposed to #0) refers to the current 
context. See the reference documentation for more information on specifying 
a level 1n upvar. 


Note 


Although omitting the level argument causes upvar to default to the 
context of the procedure’s caller, the best practice is to explicitly 
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provide a level argument of : in this case. This prevents upvar from 
raising an error if the first variable name begins with a + or digit. 


9.6 Creating New Control Structures: wrever 


The upiever command is a cross between evai and upvar. It evaluates its 
argument(s) as a script, just like evai, but the script is evaluated in the 
variable context of a different call stack level, like upvar. With upieve1 you 
can define new control structures as Tcl procedures. For example, here is a 
new control flow command called ao: 


proc do {varName first last body} { 
upvar $varName v 
for {set v $first} {$v <= $last} {incr v} { 
uplevel Sbody 
} 


} 


The first argument to ao is the name of a variable. ao sets that variable to 
consecutive integer values in the range between its second and _ third 
arguments and executes the fourth argument as a Tcl command once for each 
setting. Given this definition of ao, the following script creates a list of 
squares of the first five integers: 


set squares {} 
do iis { 


lappend squares [expr $i*$i] 
set squares 
=>2.4 $ 16°25 
set i 
BAe 


The ao procedure uses upvar to access the loop variable (: in the example) as 
its local variable v. Then ao uses the ror command to increment the loop 
variable through the desired range. For each value, it invokes upieve1 to 
execute the loop body in the variable context of the caller; this causes 
references to the variables squares and i in the body of the loop to refer to 
variables in ao’s caller. If eva1 were used instead of upievei, squares and i 
would be treated as local variables in ao, which would not produce the 
desired effect. 
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Note 


This implementation of ao does not handle exceptional conditions 
properly. For example, if the body of the loop contains a retum 
command, it causes only the ao procedure to return, which is more like 
the behavior of break. A return that occurs in the body of a built-in 
control flow command such as for Or wnite causes the procedure that 
invoked the command to return. In Chapter 13 you will see how to 
implement this behavior for ao. 


As with upvar, upleve: takes an optional initial argument that specifies an 
explicit stack level. In the common case where the script should be 
evaluated in the context of the caller, the best practice is to explicitly 
indicate a level of 1. Otherwise, a script argument beginning with a + 
character or digit would be misinterpreted as the level argument. See the 
reference documentation for details. 


9.7 Applying Anonymous Procedures 


Not only do procedures provide a mechanism for modular programming, but 
they also have performance advantages in Tcl. Internally, the body of a 
procedure is transformed into an efficient bytecode representation. 
Procedures also offer a local scope, allowing for the creation of transient 
variables without potential naming conflicts with existing variables. There 
are occasions when you might desire the efficiency or encapsulation of a 
procedure but require the procedure for a single purpose or a limited time. 
Code callbacks, such as for widget commands and file event handlers, and 
one-shot transformational functions are typical examples. 

The appiy command, introduced in Tcl 8.5, provides the ability to apply an 
anonymous function to a set of arguments: 


apply fargList body ?namespace?} ?arg1 arg? ...? 


The first argument to appiy is a procedure definition, consisting of a two- or 
three-element list. The first element is the formal procedure argument, 
defined in the same way as for proc. The second element is a Tel script 
implementing the body of the procedure. The third element is optional; if 
provided, it specifies a namespace in which to evaluate the procedure. (See 


215 


Chapter 10 for a discussion of namespaces.) Subsequent arguments to appiy 
are the actual values assigned to the procedure arguments. 

As an example, consider the following anonymous procedure that calculates 
the sum of several numbers: 


apply { {args} { 
set total 0 
foreach val Sargs { 
set total [expr {$total + $val}] 


} 


return S$total 
}}1234567 
=> 28 
set total 
@ can't read "total": no such variable 


In this case, the numbers 1 through 7 are assigned as a list to the anonymous 
procedure’s formal argument args, just as they would be for a named 
procedure created with proc. The anonymous procedure then calculates and 
returns the sum of the values. Note that in this example the variable totai is 
local to the procedure and is automatically deleted on the procedure’s 
termination. 

AS a more representative example, consider the task of sorting a list based 
on the string length of each element. The isort command (discussed in 
Chapter 6) doesn’t have an option for sorting by element length, but you can 
use the -commana option to specify your own sorting procedure. The procedure 
must accept two elements, returning an integer less than, equal to, or greater 
than zero if the first element is to be considered less than, equal to, or 
greater than the second, respectively. Although you could define a named 
procedure to implement the comparison, you can also employ an anonymous 
procedure: 


set states {California Delaware Hawaii Indiana Iowa} 
lsort -command { apply { {el e2} { 
expr {[string length $e1] - [string length $e2] } 
} } } $states 
= Iowa Hawaii Indiana Delaware California 


Another use of an anonymous procedure is to implement a callback, such as 
for variable tracing. (See Chapter 15 for more information on tracing 
variable access.) Variable trace procedures are called with three values, 
describing the variable and the type of access. In this example, an 
anonymous procedure reports the new value of the traced variable on the 
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console: 


set vbl "initial" 

trace add variable vbl write {apply {{v1 v2 op} { 
upvar 1 $vl v 
puts "updated variable to \"$v\"" 


b}} 


set vbl 123 

=> updated variable to "123" 
set vbl abc 

=> updated variable to "abc" 


Additionally, appiy can be used as a building block for implementing various 
functional programming constructs. You can find several examples of this on 
the Tcler’s Wiki (nttp://wiki.tci.tk). The following demonstrates the 
implementation of a map command, which accepts a list and returns a new list 
generated by applying a transformation to each element of the original list: 


proc map {lambda list} { 
set result {} 
foreach item $list { 
lappend result [apply S$lambda $item] 
} 


return $result 


} 

map {x { expr {$x**2} }} {1 2 3 4 5} 
Sel 2.9 56°25 

map {x {return [list [string length $x] $x]}} {A BB CCC DDDD} 
=> {1 A} {2 BB} {3 CCC} {4 DDDD} 
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10. Namespaces 


The Tel interpreter collects all commands and global variables into groups 
called namespaces, so that commands and variables within one namespace 
don’t interfere with commands in another. These namespaces themselves are 
arranged in a tree, and commands in one namespace can be imported into 
another. The root of the tree is the global namespace, and it contains all 
commands and variables that are not created explicitly within some other 
namespace. 

Commands and variables may be created within or used from out of any 
existing namespace. This is done by prefixing the name of the namespace to 
the command or variable name, separated by the namespace separator, a 
double colon. The name of the global namespace is an empty string, but a 
double colon is usually used in-stead as a synonym. 

One of the main uses of namespaces is as a mechanism for building a 
package of related commands. Namespaces provide assistance for this in 
the form of ensembles, which are used to group the public API of a 
namespace together and present it in the common command and 
subcommand style. 


10.1 Commands Presented in This Chapter 


® namespace children ?namespace? ?pattern? 
Returns a list of all child namespaces of the given namespace, or the current 
namespace if nO namespace argument is present. If pattern 18 specified, it 
returns only those child namespaces whose (unqualified) name matches the 
glob pattern. 

® namespace code script 
Returns scripe in a form that, when evaluated, will cause script to be 
evaluated in the current namespace. This 1s ideally suited to callback script 
generation, because if the script callback has any arguments appended to it 
at callback time, those arguments will be passed correctly as extra 
arguments to the command in scrip¢ after allowing for namespace handling. 

® namespace current 
Returns the fully qualified name of the current namespace. 


® namespace delete ?namespace ...? 


219 


Deletes each of the named namespaces. 


namespac nsemble create ?option value ...? 
Creates an ensemble bound to the current namespace and returns the fully 
qualified name of the ensemble. 


® namespac nsemble configure ensemble ?option? ?value ...? 


Configures the ensemble named ensempie. If NO option 1s specified, it returns a 
dictionary of all options and their values. If option is present but no vaiue, it 
returns the current value of that option. Otherwise there should be a list of 
options and the values to set those options to, and the result is the empty 
String. 


° namespac nsembl xists ensemb1l 


Returns 1 1f ensempie 18 an ensemble command, o otherwise. 


® namespace eval namespace body 


Executes a script inside the namespace called namespace, creating the 
namespace if it does not already exist. The result of the command is the 
result of the last command executed 1n boay. 

® namespace exists namespace 
Returns : if the named namespace exists, o otherwise. 

® namespace export ?-clear? ?pattern ...? 
If one or more string match—Style patterns are specified, appends them to the 
current namespace’s list of command export patterns. If -ciear is also 
specified, it clears the list of export patterns first. Ifno patterns are present, 
it returns the current list of export patterns. 


®* namespace forget ?pattern ...? 


Each command previously imported into the current namespace that matches 
any of the supplied string matcn-Style patterns is “forgotten”; that is, it is 
deleted from the current namespace. Commands that were not imported and 
the original exported commands are unaffected. 


®* namespace import ?-force? ?pattern ...? 


Imports commands matching one or more string matcn—Style patterns into the 
current namespace. The commands must also match one of their source 
namespace’s export patterns. Each pattern is a qualified glob pattern, 
consisting of a literal namespace name prefix and a glob pattern suffix. The 
local name in the current namespace of each imported command will be the 
same as the local name of the command in the namespace from which it was 
imported. It is an error to import a command over an existing command 
other than a previous import of the same command unless the -force option is 
specified, when the existing command 1s silently replaced instead. 


* namespace origin command 


Returns the fully qualified name of the command that implements commana. If 
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command Was imported from another namespace, it returns the qualified name 
of the real implementation. 

® namespace parent ?namespace? 
Returns the name of the parent namespace of namespace, or the parent 
namespace of the current namespace if no namespace is supplied. 

® namespace path ?list? 
Sets or returns the current namespace’s name resolution path. If iis¢ 1s 
present, the name resolution path is set to the list of namespaces named in it. 
If 1ist 1s absent, the current name resolution path is returned. 

® namespace qualifiers string 
Returns everything up to the last namespace separator in string. If string does 
not contain any namespace separators, it returns the empty string. Note that 
this command does not check whether any namespaces exist. 

® namespace tail string 
Returns everything after the last namespace separator in string. If string does 
not contain any namespace separators, it returns string unchanged. Note that 
this command does not check whether any namespaces exist. 


® namespace unknown ?script? 


Returns the current namespace’s unknown command handler script, or sets it 
to script 1f that is supplied. The default unknown command handler for all 
namespaces 1S ::unknown. 


® namespace upvar namespace otherVar localVar 


\?otherVar localVar ...? 
Maps each of the variables named otnervar in the namespace namespace to a 
local variable, 1ocaivar. The variables are linked; any change to one results 
in a change to the other. 


® namespace which ?-command|-variable? name 


Returns the fully qualified name of the entity called name. If -commana 1S given, 
and by default, name is assumed to refer to a command. If -variabie 18 given, 
name 18 assumed to refer to a variable. 


® variable varName ?value? ?varName value ...? 


Creates and refers to, and optionally initializes, variables in the current 
namespace. 


10.2 Evaluating Tcl Code in a Namespace 


To execute a script in a namespace, use the namespace eval command. This 
takes the name of a namespace in which to execute and a Tcl script to 
evaluate in that namespace, and it returns the result of executing the script. It 
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also creates the namespace if it does not already exist. The proc command 
always creates commands relative to the current namespace unless they are 
fully specified. Note that all commands in the script that are not found in the 
namespace itself are looked up in the global namespace; for example: 


proc whoAmI {} { 
return "global command" 
} 


namespace eval ns { 
proc whoAmI {} { 
return "namespace command" 
} 
} 


whoAmI 
=> global command 
ns: :whoAmI 
=> namespace command 
namespace eval ns { 
whoAmI 
} 


=> namespace command 


You can also declare a procedure within any namespace by giving a fully 
qualified name to the proc command, such as ns: :newcma. 

To delete a namespace, as opposed to a command within it, use the namespace 
delete command. This takes a list of namespaces to delete. 

Access to variables within a namespace is set up using the variable 
command. This takes the name of a variable to set up within the current 
namespace and an optional value to set the variable to. If evaluated within a 
procedure, it also arranges for the namespace variable with the given name 
to be available within the procedure without qualification. 


Zaz 


namespace eval counter { 

variable num 0 

proc next {} { 
variable num 
return [incr num] 

} 

proc reset {} { 
variable num 
set num 0 


} 
} 


counter: :next 


a: 
counter: :next 
=e2 
counter: : reset 
= 0 


counter: :next 
=> 1 


Note 


Always declare variables using the variabie command. Within a 
namespace, if you access a variable that hasn’t explicitly been 
declared as a namespace variable, Tcl first checks to see whether there 
exists a global variable with that name. If an existing global variable is 
found, Tcl uses that in favor of creating a namespace variable. 
Although this behavior might seem unexpected at first, it was designed 
for easy access to predefined global variables such as argv, env, etc., 
from within a namespace. 


The variable Command cannot initialize array values, but it can set the 


variables up within the namespace or grant access to them from a 
procedure. This means that arrays should be initialized in a separate step. 
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namespace eval catalog { 


— 


variable entries 
array set entries {} 
proc add {item} { 


variable entries 

incr entries (Sitem) 
proc getEntries {} { 

variable entries 

return [lsort [array names entries] ] 
proc countInstances {item} { 

variable entries 

return Sentries ($item) 


} 
} 


catalog::add apple 
1 


catalog::add orange 
1 
catalog::add apple 
2 


catalog::add banana 
1 

catalog: :getEntries 
apple banana orange 


catalog::countInstances apple 
2 


te 


When you need to generate a script for handling a callback, such as when 
working with the isort command’s -commana option, Widget -commana Options, or 
the arter OF trace commands discussed later in this book, it is best to generate 
that script using namespace code. This wraps additional code around the script 
to ensure that it gets evaluated in the current namespace rather than in the 
namespace in which it was invoked. For example, we could extend the 
previous example with the ability to save the catalog to a file so that it does 


not get 


lost when we quit the interpreter, and we could then set it up so that 


the catalog gets saved automatically every 10 seconds: 
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namespace eval catalog { 
proc save {file} { 
variable entries 
set £f [open $file w] 


puts $f [list array set ::catalog::entries \ 
{array get entries] ] 
close $f 


} 


proc autocommit {interval file} { 
after S$interval [namespace code [list \ 
autocommit Sinterval $file] ] 
save $file 


} 


# Save to catalogDB.tcl every 10 seconds 
autocommit 10000 catalogDB.tcl 


10.3 Manipulating Qualified Names 


Everything in a namespace can be accessed via its qualified name. This 
consists of the name of the namespace with :: and the local name of the 
command, variable, or subnamespace appended. These qualified names may 
be either absolute, being specified with a :: at the front referring to the 
global namespace, or relative to the current namespace (without the double 
colon). This is analogous to working with absolute versus relative paths on 
a file system. 

For the purpose of creating qualified paths, the global namespace itself can 
be referenced with just the :: prefix. Thus, ::set refers to the set command in 
the global namespace, and ::env refers to the global env array. The cataiog 
namespace from the previous section was created as a direct child of the 
global namespace. Therefore, in the global namespace you can invoke the 
aaa procedure using a relative qualified name of counter: :aaa. From any other 
namespace you would need to use the absolute qualified name, : : counter: :ada. 
To work with such qualified names, Tcl provides a number of tools. To get 
the namespace part of a qualified name, use the namespace qualifiers Command. 
It returns the namespace part of the name. The local part of the qualified 
name can be obtained using the namespace tail command. 
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namespace qualifiers alpha: :beta 
=> alpha 

namespace qualifiers ::alpha::beta::gamma 
=> ::alpha ::beta 

namespace qualifiers delta 


= 
namespace tail alpha ::beta 
=> beta 
namespace tail ::alpha::beta::gamma 
=> gamma 
namespace tail delta 
=> delta 


To construct a qualified name from parts, just put them together with a literal 
::. Note that if you are holding the namespace name in a variable, you 
should use one of the alternative forms when substituting the variable 
because the :: is otherwise interpreted by the s variable substitution. 


set theNS ::alpha::beta 

set theCommand $theNS: :gamma 

@ can't read "theNS::gamma": no such variable 
set theCommand ${theNS}::gamma 

= ::alpha::beta::gamma 


10.4 Exporting and _ =Importing Namespace 
Commands 


If a namespace presents a public API of some form, it should be exported 
from the namespace using the namespace export Command. This command 
adjusts and inspects a list of glob patterns associated with the namespace 
that specify which commands defined within the namespace form its public 
API. 

Given a public API exported by some namespace, you can import 
commands from that API into another namespace so that you can use them 
without needing the fully qualified name of the command. This is managed 
by the namespace import Command, which takes a list of glob patterns that 
specify the commands to import (out of the set exported by the other 
namespace): 
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namespace eval src { 


proc a {} {return "alpha"} 
proc b {} {return "beta"} 
proc ete {} {return "..."} 


namespace export a b 


} 


namespace eval dst { 


namespace import ::src::* 
proc c {} { return "charlie"} 
expr {"{a] [b] [c]"} 


} 


= alpha beta charlie 


Note 


The global namespace does not export any commands by default, and 
this namespace is left to the application script to manage by 
convention. Library packages should not export commands from or 
import commands into the global namespace. 


The namespace import Command has snapshot semantics; it imports only those 
commands that are exported at the time when it is called. Also, it does not 
overwrite any existing commands, including preexisting imports, by default. 
This behavior can be overridden by the -sorce option. If you wish to remove 
previously imported commands from a namespace without the risk of 
deleting other commands you may have created, you should use the namespace 
forget Command. 


10.5 Inspecting Namespaces 


Tcl provides a number of tools for inspecting namespaces. You can discover 
what the current namespace is with the namespace current command, what the 
name of its parent namespace is with namespace parent, and what the child 
namespaces of the current namespace are with namespace children (which takes 
optional namespace and glob pattern arguments for specifying the 
namespace to inspect and for constraining the list of returned namespaces 
respectively): 
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namespace eval example { 
namespace current 


=> ::example 
namespace eval example { 
namespace parent 


= 33 
namespace eval example { 
namespace eval subNS { 
namespace current 


=> ::example: :subNS 
namespace eval example { 
namespace eval abcl {} 
namespace eval abc2 {} 
namespace eval abc3 {} 
} 
lsort [namespace children example abc*] 
=> ::example::abcl ::example::abc2 ::example::abc3 


To discover the commands and variables defined in a namespace, use the 
normal into subcommands, and qualify the pattern argument with the name of 
the namespace that you wish to inspect: 


namespace eval example { 


proc egl {} {} 
proc eg2 {} {} 


} 


lsort [info command example: :*] 
=> ::example::egl ::example::eg2 


On the other hand, if you know the unqualified name of a command or 
variable, you can get its fully qualified name using namespace which! 


namespace eval example { 
proc eg {} {} 
proc env {} {} 
list [mamespace which eg] [namespace which set] \ 
{namespace which -variable env] 


} 


> ::example::eg ::set ::env 


The current list of export patterns can be obtained by using the namespace 
export Command with no arguments. 
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To discover which namespace originally exported a potentially imported 
command, use the namespace origin Command. This command returns the fully 
qualified name of the command from which the argument command came; if 
the command was defined in the local namespace, this is just the fully 
qualified name of the command. 


namespace eval example { 
proc egl {} {} 
proc eg2 {} {} 
namespace export * 


namespace import example: :* 
namespace origin egl 
= ::example: :egl 


Note that namespace origin can discover the origin of a command even if it has 
been renamed: 


rename eg2 example2 
namespace origin example2 
=> -:example::eg2 


10.6 Working with Ensemble Commands 


A very common system of representing a collection of related commands is 
as a group of subcommands within an ensemble. This is a common pattern 
within Tcl—for example, the string, namespace, aNd clock commands all follow 
it—and it is also common in Tk and many extensions. Tcl provides an 
ensemble mechanism to allow script programmers to create their own 
groups of related commands with minimal effort. This is done through the 
namespace ensemble Command. 


10.6.1 Basic Ensembles 


The easiest way to create an ensemble is to use namespace export (as described 
in the preceding section) to publish the commands in a namespace that form 
the API. Using namespace ensemble create Without any extra arguments in that 
namespace creates an ensemble based on the public API with the same fully 
qualified name as the namespace itself. You can also test whether a 
command is an ensemble using namespace ensemble exists, Which returns true if 
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the argument given is the name of a command that is an ensemble: 


namespace eval example { 
proc plus {x y} {expr {$x + $y}} 
proc multiply {x y} {expr {$x * $y}} 
proc minus {x y} {expr {$x - $y}} 
namespace export add multiply minus 
namespace ensemble create 


} 
=> ::example 
example add 2 3 
= 5 
example multiply 6.0 7 
=> 42.0 
namespace ensemble exists example 
= 2 
namespace ensemble exists example: :add 
=> 0 


The subcommands of a namespace may be abbreviated uniquely in use; the 
ensemble command invokes the correct subcommand or, 1f the abbreviation 
is not unique, throws a suitable error: 


example mul 3.11.3 

=> 4.03 
example m -4 -5 

@ unknown or ambiguous subcommand "m”: should be add, minus, or 
multiply 


Note that procedures placed inside an ensemble generate an ensemble- 
aware error message when they are invoked with an incorrect number of 


arguments: 


example mul 42 
@ wrong # args: should be "example mul x y" 


10.6.2 Placing Ensembles Inside Ensembles 


You can nest ensembles inside ensembles. This is useful when the ensemble 
is modeling a complex API, which is fairly common in situations like Tk 
widgets. In the following example, the compute command has two general 
subcommands doing computations of the area of shapes and the volume of 
solids. These subcommands in turn have their own specialized sub- 
subcommands for each of the types of shapes or solids that they support: 
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namespace eval compute { 

variable pi 3.1415927 

namespace export * 

namespace ensemble create 

namespace eval area { 
namespace export * 
namespace ensemble create 

} 

namespace eval volume { 
namespace export * 
namespace ensemble create 


} 
} 


proc compute::area::circle {radius} { 
variable ::compute::pi 
return [expr {$pi * $radius**2}] 


} 


proc compute::area::square {side} { 
return [expr {$side ** 2}] 
} 


proc compute::volume::sphere {radius} { 
variable ::compute::pi 
return [expr {4 * Spi / 3 * Sradius**3}] 


} 

proc compute::volume::cube {edge} { 
return [expr {Sedge ** 3}] 

} 


compute ? 

@ unknown or ambiguous subcommand "?": should be area, or volume 
compute area ? 

@ unknown or ambiguous subcommand "?”: should be circle, or square 
compute area circle 4 

= 50.2654832 
compute vol sphere 2 

= 33.5103221333 


10.6.3 Controlling the Ensemble Configuration 


The namespace ensemble Command create takes a number of option-value pairs, 
most of which can also be controlled by using the namespace ensemble configure 
subcommand. You can define the list of subcommands explicitly using the - 
subcommands Option. This is useful in situations where you are not defining an 
ensemble to have exactly the publicly exported commands of a namespace, 
such as when using the global namespace. You can also specify whether 
unambiguous prefixes of commands are permitted by using the -presix option 
(true by default), or what the command created by the namespace ensemble creat 

subcommand is by using the -commana option. The namespace that the 
ensemble is bound to is readable by fetching the -namespace option, though this 
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cannot be set and is determined automatically at creation time. 

There are two other configurable options: -map and -unknown. The -map option 
contains a dictionary that maps subcommand names to lists of words. Each 
of these lists gives a replacement for the first two words of the command 
(that is, the ensemble command name and the subcommand name), and the 
overall command created is executed to implement the subcommand being 
executed. This provides a general rewriting scheme that allows additional 
arguments to be passed to any subcommand implementation, which can be 
extremely useful. 


proc raisePower {power value} { 
return "$value * $power =\ 
[expr {$value ** $power}]" 


} 


namespace ensemble create -command power -map { 
square {raisePower 2} 
cube {raisePower 3} 
sgroot {raisePower 0.5} 
invert {raisePower -1} 
} 


power cube 4.0 

= 4.8 “Ze 66.9 
power sqroot 49 

= 49 * 0:5 = 7.0 
power inv 0.0625 

=> 0.0625 *~ -1 = 16.0 


As you can see, the -map option allows for the construction of very complex 
behavior with a minimum of effort. 


10.6.4 Handling Unknown Ensemble Subcommands 


The -unknown option is a list of words that forms a command prefix that is 
used whenever a subcommand cannot be resolved to one of the existing 
subcommands of an ensemble. When an unknown subcommand is 
encountered, all the arguments to the ensemble (including the name of the 
ensemble itself) are appended to the command prefix (after proper quoting), 
and the resulting command is executed. If the returned list 1s empty, the 
ensemble reparses the subcommand name and dispatches to the command 
that now implements the subcommand (that is, if the unknown handler 
updated at least one of the -map OF -subcommana Options of the ensemble) or 
generates an error. If the returned list 1s non-empty, it consists of the full list 
of arguments (including the command name) to execute for the subcommand, 
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which allows for one-off mappings. 

The -unknown option is useful when you are creating an overloading of one of 
the core Tcl commands, as it allows you to do so without having to 
enumerate the whole list of subcommands that the core Tcl command 
supports. For example, the string command does not have a subcommand to 
reverse a string, but it is easy to add one like this: 


rename string strCore 
proc strReverse {string} { 
set result {} 
for {set i [strCore length $string]} {$i>0} {} { 
incr i -1 
append result [strCore index $i] 


} 


return $result 
proc unknownStrcCmd {string subcommand args} { 
puts "passing $subcommand through to strCore" 
return [list strCore $subcommand {expand}S$args] 
namespace ensemble create -command string -map { 
reverse {strReverse} 
repeat {strCore repeat} 
replace {strCore replace} 
} -unknown unknownStrCmd 


All the unknown handler (unknownstrcma) does is write an informative message 
and hand subcommands through to the (renamed) core version of the string 
command. Note that the repeat and repiace subcommands have been explicitly 
added to the ensemble subcommand map so that unambiguous subcommand 
prefixing works as expected. 


string reverse abc 

=> passing length through to strCore 
passing index through to strCore 
passing index through to strCore 
Passing index through to strCore 
cba 


For performance reasons, it is often better for unknown handlers to update 
the ensemble with the subcommand mapping, like this: 
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proc unknownStrCmd {string subcommand args} { 
catch {strCore $subcommand} msg 
if {![string match {*: must be *} $msg]} { 
puts “adding $subcommand to ensemble" 
set map [namespace ensemble \ 
configure $string -map] 
dict set map $subcommand [list \ 
strCore $subcommand] 
namespace ensemble configure $string -map $map 


} 


puts "passing $subcommand through to strCore" 
return [list strCore $subcommand {expand}$args] 


} 


string reverse abcdef 

=> adding length to ensemble 
Passing length through to strCore 
adding index to ensemble 
passing index through to strCore 
fedcba 


Note that the messages about the iengtn and index subcommands are printed 
only the first time they are used in the ensemble. After that, the ensemble 
contains a dynamically built cache of the mapping. 


10.7 Accessing Variables from Other Namespaces 


Sometimes you need to access variables from a namespace other than the 
current one, either because the variable represents some shared state, or 
because it has some special properties. There are several ways to do this. 
First, you can use the fully qualified name of the variable. This is useful 
mainly when the variable is accessed from one place in the code or when it 
is a special variable such as the : :env array. 

Second, you can use the fully qualified name with gioba1, upvar, OF variable tO 
import the variable into the current namespace. This is often used when only 
a limited number of variables are required and their names are fixed. 

Third, you can use namespace upvar to Import a group of variables from a 
single namespace. This is particularly useful when that namespace 
represents a context for some operation and the names of the variables 
within that potentially variable namespace are static. 
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proc blob {name a b c} { 

namespace eval $name {} 

namespace upvar $name a va b vb ¢ ve 

set va Sa 

set vb $b 

set vc $c 

namespace ensemble create -map [list \ 
set [list ::blobSet $name] \ 
sum [list ::blobSum $name] \ 
end [list ::blobEnd $name] \ 


}) -command Sname 
} 
proc blobSet {ns var value} { 
# more elegant than: upvar #0 ${ns}::${var} v 
namespace upvar $ns $var v 
set v $value 
return 
} 
proc blobSum {ns} { 
namespace upvar $ns ava bvb c ve 
return [expr {$va + $vb + $vc}] 
} 
proc blobEnd {ns} { 
rename $ns {} 
namespace delete $ns 
} 
# Now for some example usage... 
blob example 1 2 3 
=> ::example 
example set a 4 
example sum 
=> 9 
example set b 5 
example sum 
=> 12 
example end 


10.8 Controlling the Name Resolution Path 


When a command is invoked within a namespace, the command is looked up 
from the name in a process known as resolution. Names starting with the 
namespace separator :: are always looked up from the global namespace, 
but names containing a namespace separator that is not at the front of the 
name are resolved relative to either the current namespace or, if that fails, 
relative to the global namespace. 

When a name does not contain a namespace separator at all, it is resolved 
using the namespace’s resolution path. This path is a list of namespaces that 
is controlled using the namespace path command, and it always behaves as if 
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the current namespace is at the front of the list and the global namespace is 
on the end. The command is looked up by checking each namespace on the 
path in order to see if the command is defined there. The namespace path 


command sets the path to the given list or returns the current path if no list is 
given. 


For example, this allows a service namespace to be spliced in, which 
allows result generation to be done using the puts command. This makes 
going from interactive testing to deployment extremely easy. 


namespace eval ::collector { 
proc collect {command args} { 
variable accumulator {} 
set ns [namespace parent \ 
[namespace origin $command] ] 
namespace eval $ns { 
namespace path ::collector 

} 


$command {expand}$args 
namespace eval $ns { 

namespace path {} 
} 


append accumulator "\[generated \ 
{string length S$accumulator)] \ 
characters\]" 
return [string trimright S$accumulator \n] 
} 
proc puts {args} { 
if {{llength $args] == 1} { 
variable accumulator 
append accumulator [lindex $args 0] \n 
return 
} 
::puts {expand}S$args 
} 
} 
namespace eval ::example { 
proc makeMessage {name age} { 
puts "Hello $name" 
puts "You are Sage years old" 
} 
} 
collector::collect ::example::makeMessage \ 
"Joe Bloggs" "37 and three quarters" 
= Hello Joe Bloggs 
You are 37 and three quarters years old 
[generated 57 characters] 


The namespace path Command can also be used to make a namespace system 
that functions very much like objects and classes: 
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set counter 0 

proc new {class} { 
global counter 
set cmd ::obj [incr counter] 
namespace eval $cmd [list namespace path ::$class] 
proc $cmd {args} "namespace eval $cmd \Sargs" 
return $cmd 


} 


This works by creating a new namespace for every command and setting 
that namespace up to resolve its commands using the class namespace 
before the global namespace. It then creates a command that just evaluates 
its arguments in the namespace, which has the effect of resolving the 
subcommand in the class as there are no commands in the object namespace. 
The class method procedures should use the upvar 1 command to access the 
object namespace; the original caller’s stack frame can be reached using the 
upvar 2 COmmand, and the class’s namespace should be accessed using the 
variable Command: 


namespace eval example { 
proc foo {args} {puts foo:$args} 
proc bar {args} {puts bar:$args} 
proc set {var args} { 
upvar 1 $var v 
set v {expand}Sargs 
} 
proc setClass {var args} { 
variable $var 
set $var {expand}Sargs 
} 
} 
set ol [new example] 
=> ::0b31 
$ol fooabe 
= foo:a bec 


Notice that it is easy to work with variables in the object, just by using 
normal Tcl commands with the object name prefixed: 


$01 set x 0 
=>0 


Also note that the preceding variable is created in the object’s namespace 
and not in the class’s namespace. The variables in the class are unrelated 
unless explicitly synchronized. 
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incr ::01::x 
$ol set x 
— 
set ::example::x "In the class!" 
Sol set x 
=a 
$ol setClass x 
= In the class! 
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11. Accessing Files 


This chapter describes Tcl’s commands for dealing with files and 
directories. The commands allow you to read and write files sequentially or 
in a random-access fashion. They also allow you to retrieve information 
kept by the system about files, such as the time of last access. You can 
rename, copy, and delete files. Last, these commands can be used to 
manipulate file names; for example, you can remove the extension from a 
file name or find the names of all files that match a particular pattern. 


11.1 Commands Presented in This Chapter 


This chapter describes the following commands for manipulating files and 
directories. Most of these commands also work with interprocess pipes and 
network sockets, covered in Chapter 12. In Tcl terminology, files, pipes, and 
network sockets are considered channels. All of the I/O-related commands 
work on any channel. 

° cd ?dirName? 
Changes the current working directory to airvame, or to the home directory 
(as given by the somz environment variable) if airvame isn’t given. Returns an 
empty string. 

® glob ?0ption ...? ?--? pattern ?pattern...? 
Returns a list of the names of all files that match any of the pattern arguments 
(special characters 2, «, 3, {}, and \). The optional -- argument signals the 
end of options. See the reference documentation for more information on 
allowed options. 


pwd 
Returns the full path name of the current working directory. 
® chan close channelID 
close channelID 
Closes the channel given by channeirp. Returns an empty string. The chan close 
command, introduced in Tcl 8.5, simply incorporates the ciose functionality 
into the chan ensemble. 


® chan eof channelID 


eof channelID 


Returns : if an end-of-file condition has occurred during the most recent 
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read from channeizp, 0 Otherwise. Starting with Tcl 8.5, cor is deprecated in 
favor Of chan eof. 

® file option name ?arg arg ...? 
Performs one of several operations on the file name given by name or on the 
file to which it refers, depending on option. See this chapter and the 
reference documentation for more information. 

® chan flush channelID 

flush channelID 

Writes out any buffered output that has been generated for channeirp. Returns 
an empty string. Starting with Tcl 8.5, fiusn 1s deprecated in favor of chan 
flush. 

® chan gets channelID ?varName? 

gets channelID ?varName? 

Reads the next line from channeirp and discards its terminating end-of-line 
character(s). If varname 18 specified, it places the line in that variable and 
returns a count of characters in the line (or -: for end of file). If varname isn’t 
specified, it returns the line of characters read (or an empty string for end of 
file). The chan gets command, introduced in Tcl 8.5, simply incorporates the 
gets functionality into the chan ensemble. 


© open name ?access? 


Opens the file name in the mode given by access. access may be r, r+, w, wt, a, OF 
a+ or a list of flags such as rnonzy; it defaults to r. Returns a file identifier for 
use 1n other commands like gets and close. If the first character Of name 1S |, a 
command pipeline is invoked instead of a file being opened (see Section 
12.4 for more information). 


* chan puts ?-nonewline? ?channelID?string 


puts ?-nonewline? ?channelID?string 
Writes string tO channeirp, appending a newline character unless -nonewiine 18 
specified. channeirp defaults to stdout. Returns an empty string. The chan puts 
command, introduced in Tcl 8.5, simply incorporates the puts functionality 
into the chan ensemble. 
® chan read ?-nonewline? channelID 

chan read channelID numChars 

read ?-nonewline? channelID 

read channeliID numChars 
Reads and returns the next numchars characters from channeizp (or up to the end 
of the file, if fewer than numchars characters are left). If numchars is omitted, it 
reads and returns the remaining characters of the file; when combined with - 
nonewline, the final newline, if any, is dropped. The chan reaa command, 
introduced in Tcl 8.5, simply incorporates the reaa functionality into the chan 
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ensemble. 
® chan seek channelID offset ?origin? 
seek channelID offset ?origin? 
Positions channeirp SO that the next access starts at orrset bytes from origin. 
origin May be start, current, OF ena and defaults to start. Returns an empty 
string. Starting with Tcl 8.5, seex 1s deprecated in favor of chan seex. 
® chan tell channelID 
tell channeliD 
Returns the byte offset from the start of the file of the current access position 
for channeirp. Starting with Tcl 8.5, te11 1s deprecated in favor of chan te11. 
® chan configure channelID ?0ptionName? ?value? 
?optionName value ...? 
fconfigure channelID ?optionName? ?value? 
?optionName value ...? 
Queries or sets the configuration options of the channel channeirp. If no 
optionName OF value arguments are supplied, the command returns a dictionary 
of all configuration options and their values. If optionname 18 supplied but no 
value, the command returns the current vaiue of the given option. If one or 
more pairs Of optionnvame and vaiue are supplied, the command sets each of the 
named options to the corresponding value; in this case the return value is an 
empty string. See the text and the reference documentation for a description 
of the supported options. Starting with Tcl 8.5, configure 1s deprecated in 
favor Of chan configure. 
® chan copy inputChan outputChan ?-size size? 
2?-command callback? 
fcopy inputChan outputChan ?-size size? 
?-command callback? 
Copies data from the channel inputchan, which must have been opened for 
reading, to the channel outputcnan, which must have been opened for writing. 
The chan copy command transfers data from inputchan until either the end of 
file or the maximum of size bytes has been transferred, if specified. By 
default, the command blocks transfer takes place in the foreground, and it 
returns the number of bytes written to cutputcnan. If you provide the -commana 
option, chan copy returns immediately, and once the copy is completed, 
callback 18 invoked with one or two additional arguments that indicate how 
many bytes were written to outputcnan. If an error occurred during the 
background copy, the second argument is the error string associated with the 
error. Starting with Tcl 8.5, scopy is deprecated in favor of chan copy. 


11.2 Manipulating File and Directory Names 
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Every file has a name. File names are specified in Tcl using the normal Unix 
syntax. For example, the file name «/y/z refers to a file named z that is 
located in a directory named y, which in turn is located in a directory named 
x, which must be in the current working directory. The file name /top refers 
to a file top in the root directory. You can also use tilde notation to specify a 
file name relative to a particular user’s home directory. For example, the 
name ~ouster/mbox refers to a file named mbox in the home directory of user 
ouster, and ~/mbox refers to a file named mbox in the home directory of the user 
running the Tcl script. These conventions (and the availability of tilde 
notation in particular) apply to all Tcl commands that take file names as 
arguments. 

Windows systems differ from these Unix conventions. For Windows 
systems, a backslash separates directories, rather than a forward slash. The 
backslash, \, can be problematic in Tcl and other languages based on C 
programming conventions. You normally need to escape a backslash with a 
second backslash in a context where Tcl can perform substitutions on the 
path (for example, \\apps\tci), or else protect the path from substitution (for 
example, {\apps\tc1}). This gets more complicated with network shares, 
when there are two backslashes that must be escaped, as 1n \\\\nost\\share. In 
addition, Windows disk drives do not get mounted under one root directory 
(as on Unix, Linux, and Mac OS X platforms). Instead, Windows uses a 
drive letter, such as c:, to indicate the disk drive. 

To handle the file-naming differences, use the Tcl fi1e join and file split 
commands to properly combine file names with directory names in a cross- 
platform manner. ¢iie is a general-purpose command with many options that 
can be used both to manipulate file names and to retrieve information about 
files. The commands in this section operate purely on file names. They make 
no system calls and do not check to see if the names correspond to actual 
files. 

Consider the following example, which generates a full path name to a file 
relative to the user’s home directory: 


set env (HOME) 
=> C:\Documents and Settings\Owner 
file join Senv(HOME) lib mylib.tcl 


~ 


=> C:/Documents and Settings/Owner/lib/mylib.tcl 


Notice that the ri1e join command returns a Unix-style path that contains / 
characters for directory delimiters, no matter the original format of the 
individual path components. You can use a “Tcl-native” path format like this 
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with all Tcl commands that access the file system, as well as paths with the 
platform-specific directory delimiter. In addition, 1f any component starts at 
the root level, such as with a leading /, the fi1e join command discards all 
the previous components. 


Note 


Use the tiie join command so that your scripts are not inadvertently tied 
to just one platform, such as Unix or Windows. 


Note that some directory names include spaces. Tcl commands use spaces 
as separators, so you need to properly group the arguments to the file join 
command; for example: 


file join c:/ {Program Files} Tcl tclsh.exe 
=> c:/Program Files/Tcl/tclsh. exe 


Use the site spiit command to break a file name path into its component 
parts; for example: 


file split x/y/z 
>xXVZ 


The fiie nativename Command returns a file name formatted for native usage. 
This is especially useful when you call the exec command, covered in 
Chapter 12, or when writing the path to disk or presenting the path to the 
user. With the exec command, you need to pass file names in the expected, or 
native, format. For example, the ite nativename Command expands the tilde 
character to identify a person’s home directory: 


file nativename ~ericfj/scripts/coolscript.tcl 
=> /Users/ericfj/scripts/coolscript.tcl 


file dirname removes the last component from a file name, which ostensibly 
produces the name of the directory containing the file: 


file dirname /a/b/c 
=> /a/b 

file dirname main.c 
= . 


However, the sie command does not check to be sure that there really is a 
file or directory corresponding to the name. 
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file extension returns the extension for a file name (all the characters starting 
with the last . in the name), or an empty string if the name contains no 
extension: 


file extension src/main.c 
> Cc 


file rootname returns everything in a file name except the extension: 


file rootname src/main.c 
=> src/main 

file rootname foo 
=> foo 


file tail returns the last component of a file name (that is, the name of the 
file within its directory): 


file tail /a/b/c 
= Cc 

file tail foo.txt 
=> foorixt 


The fiie normalize Command returns a unique normalized path representation 
for the file or directory, whose string value can be used as a unique 
identifier for it. A normalized path is an absolute path that has all ../ and ./ 
removed. Additionally, on Unix and Mac OS systems the segments leading 
up to the path must be free of symbolic links/aliases, and on Windows 
systems it provides the long form with that form’s case dependence; for 
example: 


file normalize ~/Documents/../tcltk/intro/examples 
=> /Users/ken/tcltk/intro/examples 


The fiie patntype command tells you information about a file name, such as 
whether it has an absolute or a relative path. This command returns either 
absolute, relative, OF volumerelative, depending on the type of the file name 
passed to the command. Relative files have names relative to the current 
working directory. Similarly, voiumereiative indicates a name relative to a 
given mounted volume or disk. You will find many voiumereiative files on 
Windows systems. Use the following commands as a guide to file pathtype: 


file pathtype foo 
=> relative 

file pathtype [pwd] 
=> absolute 
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Finally, the si1e volumes command lists all mounted volumes. On Unix and 
Mac OS X systems, it should return , for the root directory. On Windows, it 
returns a Tcl version of all mounted drives, such as <:/. 


11.3 The Current Working Directory 


With Tcl, you can provide file names that either are absolute paths or are 
named relative to the current working directory. Thus, it is often important 
to know which directory is the current working directory. 

Tcl provides two commands that help to manage the current working 
directory: pwa and ca. pwa takes no arguments and returns the full path name of 
the current working directory. ca takes a single argument and changes the 
current working directory to the value of that argument. If ca is invoked with 
no arguments, it changes the current working directory to the home directory 
of the user running the Tcl script (ca uses the value of the somz environment 
variable as the path name of the home directory). 


11.4 Listing Directory Contents 


The gice command takes one or more patterns as arguments and returns a list 
of all the file names that match the pattern(s): 


glob *.c *.h 
= main.c hash.c hash.h 


glob uses the matching rules of the string matcn command (see Chapter 5). In 
the preceding example sicp returns the names of all files in the current 
directory that end in .c or .n. gic also allows patterns to contain comma- 
separated lists of alternatives between braces, as in the following example: 


glob {{src,backup}/*. [ch] } 
=> src/main.c src/hash.c src/hash.h backup/hash.c 


giob treats this pattern as if it were actually multiple patterns, each 
containing one of the strings, as in the following example: 


glob {src/*.[ch]} {backup/*.[ch]} 
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Note 


The extra braces around the patterns in these examples are needed to 
keep the brackets inside the patterns from triggering command 
substitution. They are removed by the Tcl parser in the usual fashion 
before the command procedure for gio». 


If a giob pattern ends in a slash, it matches only directory names. For 
example, the command 


glob */ 


returns a list of all the subdirectories of the current directory. 

You can specify that the gio» command return only particular types of files 
with the -cypes option. As an argument to -types, provide a list of one or more 
of the following: » for block-special devices, - for character devices, a for 
directory, + for plain file (not directory), 1 (“ell’’?) for symbolic links, » for 
named pipes, and ; for sockets. You can also provide flags for file access 
permissions—: for read permission, w for write permission, x for execute 
permission—as well as niaden for hidden files and reaaoniy for files with only 
read permission. You can combine more than one item, but any name 
returned by gic» needs to match at least one of the file type items and all of 
the file permission items. For example, to find all files (but not directories) 
for which you have both read and write permission, use a command like the 
following: 


glob -types {frw } * 
=> b.txt c.txt 


If you have just one type of item to look for, you can use a simpler syntax: 


glob -types f * 
=> b.txt c.txt 


The -airectory option tells gio» to start ina given directory; for example: 


glob -directory /usr/local -types d * 
=> /usr/local/bin /usr/local/lib 


In this case, the « passed to gio gets interpreted inside the given directory, 
/usr/local. This option is useful if the directory name contains characters that 
would otherwise be treated as wildcards or other metacharacters in the gio» 
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pattern. 

The -patn option tells the giob command to search for files with names that 
start with the value given to -patn. This is mostly useful when you have file 
names that somehow interfere with the gic» command. You cannot use the - 
path Option with the -airectory option. The main difference is that the - 
directory Option tells gicb to start in a given directory, whereas -patn tells giob 
to use names starting with the given prefix. The value passed to -patn can 
include a directory name as well as characters that start file names. The - 
directory option accepts only the name of a directory. 

The -taiis option tells the gio» command to return only the part of the names 
that comes after the values specified in the -airectory OF -patn Options. For 
example, compare the following: 


glob -directory /usr/local -types d * 
=> /usr/local/bin /usr/local/lib 
glob -directory /usr/local -types d -tails * 


=> bin lib 


The special -join option tells gicb to treat all the remaining options as one 
large pattern, using a directory separator to join the elements. This basically 
works like the site join command but uses the results as the giop path. 

By default, gion raises an error if no files match the patterns you provide. 
You can suppress the error condition by supplying the -nocompiain option to 
glob, In which case it simply returns an empty list if no files match. 


11.5 Working with Files on Disk 


Tcl provides a variety of commands for performing operations such as 
moving, renaming, copying, and deleting files on disk. These commands 
directly invoke operating system function calls to perform their actions, so 
they are efficient as well as platform-independent. Your scripts should 
always use these Tcl commands to perform these actions rather than using 
exec to execute platform-specific commands. 


11.5.1 Creating Directories 


Create new directories with the tite mkair command, short for “make 
directory” (and named after a Unix and DOS command); for example: 
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file mkdir foo 
cd foo 
pwd 
=> /Users/ericfj/foo 


11.5.2 Deleting Files 


Delete files with the siie deiete Command: 


file delete a.txt 


You must list each file as a separate argument, such as 


file delete a.txt b.txt 


This command deletes two files. The ite aeiete command does not perform 
wildcard expansion, so the following example would delete only a file 
named +. tmp: 


file delete *.tmp 


The proper way to handle such a case is to use the gic» command to return a 
list of files matching the pattern, then use Tcl’s argument expansion syntax to 
provide the list elements as separate arguments to file delete! 


file delete {*}[glob *.tmp] 


You can use file delete to delete a directory simply by providing the 
directory’s name as an argument. However, file ceiete raises an error if the 
directory is not empty: 


file delete foo 
@ error deleting “foo": directory not empty 


Use the -force option to delete the non-empty directory. This option also 
recursively deletes all files and directories stored under the deleted 
directory, so use it with care. 


11.5.3 Copying Files 


While you can write Tcl procedures to read in the contents of a file and 
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write the output to another file, it is far easier to use the Tcl file copy 
command to copy files. The tiie copy command copies one file, the source, 
to another, the destination; for example: 


glob *.txt 

=>a.txt 
file copy a.txt b.txt 
glob *.txt 

— @a.txt b.txt 


The fiie copy command copies the file a.txt to b.txt. The gicb command then 
verifies that the new file, ».txt, now exists. 

The fiie copy command raises an error if the target file already exists, as in 
the following example: 


file copy a.txt b.txt 


@ error copying “a.txt” to "b.txt": file already exists 


You can tell the tiie copy command to overwrite the target file with the -sorce 
option: 


file copy -force a.txt b.txt 
You can also copy a number of files to a target directory. For example: 


file copy a.txt b.txt Documents 


This command copies two files, a.cxt and ».txt, to the target directory, 
Documents. In this case, the target must be a directory, not a regular file. 


11.5.4 Renaming and Moving Files 


Use the rite rename command to give a new name to a file or directory. You 
need to provide the name of the source file or directory as well as the new 
name; for example: 


file rename b.txt c.txt 


This command renames ».+xt to its rather original new name, c.txt. If the 
target already exists, you need to provide the -force option to cause file 
rename tO overwrite the target; otherwise it raises an error. 

If the target name refers to another directory, the site rename Command moves 
the file to its new location. You can also specify a directory as a source, in 
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which case the directory is either renamed or moved. 


11.5.5 File Information Commands 


In addition to the options already discussed, the si1e command provides 
many other options that can be used to retrieve information about files. Each 
of these options except stat and istat has the form 


file option name 


where option specifies the information desired, such as exists OF readable OF 
size, aNd name 1S the name of the file. 

The exists, isfile, isdirectory, and type options return information about the 
nature of a file. cite exists returns 1 ifa file by the given name exists and o if 
there is no such file or the current user doesn’t have search permission for 
the directories leading to it. ci1e istite returns : if the file is an ordinary disk 
file and o if it is something else, such as a directory or device file. site 
isdirectory returns 1 if the file is a directory and o otherwise. riie type returns 
a string such as file, directory, OF socket that identifies the file type. 

The readable, writable, aNd executabie Options return o or 1 to indicate whether 
the file exists, and if so whether the current user is permitted to carry out the 
indicated action on the file. The ownea option returns 1 if the current user is 
the file’s owner and 0 otherwise. 

The size option returns a decimal string giving the size of the file in bytes. 
filemtime returns the time when the file was last modified. The time value is 
returned in the standard POSIX form for times, namely, a signed integer 
giving the number of seconds since January 1, 1970, 00:00 UTC, otherwise 
known as the epoch time. The atime option is similar to mtime except that it 
returns the time when the file was last accessed. See Chapter 15 for more 
information on Tcl’s facilities for manipulating epoch time. 

The stat option provides a simple way to get many pieces of information 
about a file at one time. Using stat can be significantly faster than invoking 
file Many times to get the pieces of information individually. rite stat also 
provides additional information that isn’t accessible with any other file 
options. It takes two additional arguments, which are the name of a file and 
the name of a variable, as in the following example: 


file stat main.c info 


In this case the name of the file is main.c and the variable name is info. The 
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variable is treated as an array, and the elements shown in Jable 11.1 are set, 
each as a decimal string. 


Table 11.1 Array Elements Returned by the tiie stat Command 


Key Value 

atime Time of last access 

ctime Time of last status change 

dev Identifier for the device containing the file 
gid Identifier for the file’s group 

ino Serial number for the file within its device 
mode Mode bits for the file 

mt ime Time of last modification 

nlink Number of links to the file 

size Size of the file, in bytes 

uid identifier for the user who owns the file 


The atime, mtime, and size elements have the same values as produced by the 
corresponding ¢i1e options discussed earlier. For more information on the 
other elements, refer to your system documentation for the stat system call; 
each of the elements is taken directly from the corresponding field of the 
structure returned by stat. 

The istat and readiink options are useful when dealing with symbolic links, 
and they can be used only on systems that support symbolic links. tite istat 
is identical to fiie stat for ordinary files, but when it 1s applied to a 
symbolic link, it returns information about the symbolic link itself, whereas 
file stat returns information about the file to which the link points. fiie 
readlink returns the contents of a symbolic link, that is, the name of the file to 
which it refers; it may be used only on symbolic links. For all of the other 
file commands, if the name refers to a symbolic link, the command operates 
on the target of the link, not the link itself. 


11.5.6 Dealing with Oddly Named Files 


Tcl commands use a leading dash to indicate an option to the command. For 
example, the fiie copy command accepts a -force option. You'll face 
problems, though, if the files you need to work with have names starting 
with dashes. That’s because the Tcl commands assume the names starting 
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with dashes are options, not file names. 

To handle cases like this, put a double dash, --, after the command and prior 
to the names of the files. For example, to copy a file named -+force, use a 
command like the following: 


file copy -force -- -force b.txt 


This command forces the copy with the -force option, and then separates the 
command-line options from the file names with the --. 


11.6 Reading and Writing Files 


Tcl’s history as a scripting language led to an emphasis on working with text 
files. Tcl was originally created on Unix systems where most information, 
including application data and system configuration settings, is stored in 
plain text files. Thus, most Tcl file commands assume that the content of the 
files you work on is text. However, Tcl provides the capability to read, 
write, and manipulate data in binary format as well. 


11.6.1 Basic File I/O 


The Tcl commands for file I/O are similar to the procedures in the C 
standard I/O library, both in their names and in their behavior. Here is a 
script called tgrep that illustrates most of the basic features of file I/O: 


#!/usr/bin/env tclsh 
if {$arge != 2} { 

error "Usage: tgrep pattern fileName" 
} 


set f [open [lindex Sargv 1] r] 
set pat [lindex Sargv 0] 
while {[gets $f line] >= 0} { 
if {{regexp -- $pat $line]} { 
puts $line 
} 


} 


close $f 


This script behaves much like the Unix grep program, which searches files 
for text that matches a given pattern. You can invoke it from your shell with 
two arguments, a regular expression pattern and a file name, and it prints out 
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all of the lines in the file that match the pattern. 

After making sure that it received enough arguments, the script invokes the 
open Command on the file to search, which is the second argument to the 
Script. open takes two arguments: the name of a file and an access mode. The 
access mode provides information such as whether you'll be reading the file 
or writing it, and whether you want to append it to the end of file or access 
it from the beginning. The access mode may have one of the following 
values: 

* -—open for reading only. The file must already exist. This is the 
default if the access mode isn’t specified. 

* -+—open for reading and writing; the file must already exist. 

* .—open for writing only. Truncates the file (deletes all existing 
content) if it already exists; otherwise creates a new empty file. 

* wi—open for reading and writing. Truncates the file (deletes all 
existing content) if it already exists; otherwise creates a new empty 
file. 

* .—open for writing only. Sets the initial access position to the end of 
the file. Thus, writing appends to the end of the existing content 
unless you reset the access position. If the file doesn’t exist, creates 
a new empty file. 

* a+—open the file for reading and writing. Sets the initial access 
position to the end of the file. If the file doesn’t exist, creates a new 
empty file. 

The access mode may also be specified as a list of POSIX flags like roonty, 
creat, and rrunc. See the reference documentation for more information about 
these flags. 

The open command returns a string such as fiie3 that identifies the open file. 
This file identifier is used when invoking other commands to manipulate the 
open file, such as gets, puts, and close. Normally you save the file identifier 
in a variable when you open a file, and then use that variable to refer to the 
open file. You should not expect the identifiers returned by open to have any 
particular format. 

Three file identifiers have well-defined names and are always available to 
you, even if you haven’t explicitly opened any files. These are stain, stdout, 
and stderr; they refer to the standard input, output, and error channels for the 
process in which the Tcl script is executing. 


Note 
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On Windows, these default channels work only for console 
applications, not windowed applications. 


The fiie channeis command lists all open channels. For example, unless you 
have explicitly opened additional channels, this command typically returns 
only the standard I/O channels: 


file channels 
= stdin stdout stderr 


After opening the file to search, the tgrep script reads the file one line at a 
time with the gets command. sets normally takes two arguments: a file 
identifier and the name of a variable. It reads the next line from the open 
file, discards the terminating end-of-line character or characters, stores the 
line in the named variable, and returns a count of the number of characters 
stored into the variable, not including the end-of-line sequence. If the end of 
the file is reached before any characters are read, gets stores an empty string 
in the variable and returns -1. 


Note 


Tcl also provides a second form of gets where the line is returned as 
the result of the command, and a reaa command for non-line-oriented 
input. 


The tgrep script matches each line in the file against the pattern and prints it 
with puts if it matches. The pues command takes two arguments, which are a 
file identifier and a string to print. puts adds a newline character to the string 
and outputs the line on the given file. The script doesn’t specify the output 
file identifier, so it uses the default staout and the line is printed on standard 
output. 

When tgrep reaches the end of the file, gets returns -1, which ends the wniie 
loop. The script then closes the file with the ciose command; this releases the 
resources associated with the open file. In most systems there is a limit on 
how many files may be open at one time in an application, so it is important 
to close files as soon as you are finished reading or writing to them. In this 
example the ciose 1S unnecessary, since the file 1s closed automatically when 
the application exits, but a good practice. 
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11.6.2 Output Buffering 


The puts command uses the buffering scheme of the C standard I/O library. 
This means that information passed to puts may not appear immediately in 
the target file. In many cases (particularly if the file isn’t a terminal device) 
output is buffered in the application’s memory until a large amount of data 
has accumulated for the file, at which point all of the data will be written 
out in a single operation; 4KB buffers are common on many operating 
systems. (See Chapter 12 for more on buffering options.) If you need data to 
appear ina file immediately, you should invoke the fiush command: 


flush $f 


The fiusn command takes a file identifier as its argument and forces any 
buffered output data for that file to be written to the file. siusn doesn’t return 
until the data has been written. Buffered data is also flushed when a file is 
closed. 


11.6.3 Handling Platform End-of-Line Conventions 


On Unix and Linux systems each line of text in a file ends with a newline 
character (ASCII decimal 10). Old Macintosh systems (predating Mac OS 
X) used a single carriage return character (ASCII decimal 13) instead; 
modern Macintosh systems follow Unix conventions. Windows systems, 
though, use two characters: a carriage return followed by a newline. Just 
accessing text files quickly becomes an exercise in operating system 
differences. 

For the most part, Tcl handles these differences automatically. When writing 
to a file, the puts command automatically translates a newline character into 
the proper one- or two-character sequence, depending on the platform. 
Thus, you can always use \n in your Tcl scripts to indicate the end of a line. 


Note 


Remember that the puts command automatically appends an end-of-line 
sequence to the end of the string it writes. You can use the -nonewline 
option to suppress the end-of-line sequence. 
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By default, the gets command accepts any of the supported end-of-line 
conventions to determine the end of a line. The end-of-line convention can 
even change from line to line in the file. The reaa command functions the 
same way by default, and any end-of-line sequence read from the input is 
translated into a newline character in the string returned. Additionally, the - 
nonewline Option tells the reaa command to discard the trailing newline in the 
string returned if the last character (or characters) consists of an end-of-line 
sequence. 

You can use the chan configure Command (or fconfigure, for compatibility with 
older versions of Tcl) to query or modify the default end-of-line behavior 
for any given channel or file; for example: 


chan configure stdin -translation 
= auto 


With no additional argument, this command returns the end-of-line 
translation mode for the channel. You can also provide an additional 
argument to set the translation mode of the channel. A single-element list 
sets the translation for both input and output, 1f the channel is bidirectional. 
You can also provide a two-element list where the first element specifies 
the input translation and the second element specifies the output translation. 
By default, channels have a translation of auto. For input channels, auto 
means that all end-of-line sequences are treated as newlines; for output 
channels, the platform-specific convention is used automatically. A value of 
cr, 1f, OF crit indicates to use only a newline, a carriage return, or a carriage 
return—newline sequence respectively for the end-of-line convention for the 
channel. For example, setting the translation to cris on an output channel 
indicates that all newline characters should be translated to carriage return— 
newline sequences when written. In contrast, setting the translation to cr on 
an input channel indicates that only a carriage return character should be 
treated as an end of line, and when read it is translated into a newline 
character for use by Tcl. You can use a translation of binary to indicate that 
no end-of-line translations should take place; this also automatically sets the 
-encoding for the channel to pinary (see Section 11.6.4). 

Taking advantage of Tcl’s automatic conversion of line endings, you can use 
the reaa command to create an alternate implementation of the previous tgrep 
script: 
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#!/usr/bin/env tclsh 
if {Sarge != 2} {? 

error "Usage: tgrep pattern fileName" 
} 


set £ [open [lindex Sargv 1] r] 
set pat [lindex Sargv 0] 
set content [read $f] 
close $f 
foreach line [split $content "\n"] 
if [regexp -- $pat $line] { 
puts $line 
} 


} 


Note the use of the sp1it command to split the string returned by reaa at each 
newline character. This results in a list of lines over which the foreach 
command can iterate. Through the use of reaa, this script can be much more 
efficient than the previous tgrep script, which used the gets command to 
access the file system for each line. With reaa the script loads the entire 
contents of the file into memory and then checks for the matching patterns. 
This is much more efficient for files that are not too large. But using this 
technique for very large files can use too much memory, which then can 
result in paging memory out to disk, significantly slowing your system. 


11.6.4 Handling Character Set Encoding 


As discussed in Chapter 5, Tcl represents all strings internally as Unicode 
characters in UTF-8 format. However, Tcl automatically converts strings 
from the internal UTF-8 format to the system encoding and vice versa 
whenever writing and reading text on a channel. So if you are working with 
a text file that uses the same encoding as the system encoding, you don’t 
need to take any special steps for Tcl to handle the file correctly. 

On the other hand, if the file doesn’t use the same encoding as the system 
encoding (or you’d like to create a file with an encoding other than the 
system encoding), you can use the -encoding Option tO chan configure (OF 
fconfigure, for compatibility with older versions of Tcl) to specify the 
encoding for Tcl to use for the file; for example: 


chan configure $fid -encoding shiftjis 
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Note 


To prevent Tcl from performing any character encoding translation 
when working with binary files, you should use cnan configure to set the 
-translation tO binary. Not only does this prevent platform-specific end- 
of-line character translation, but it also automatically sets the -encoaing 
option on the channel to »vinary to prevent character encoding 
translation. 


11.6.5 Working with Binary Files 


Tcl assumes by default that all files are text files. As discussed in the 
previous section, if the file you are manipulating contains binary 
information, you should use chan configure to set the -translation to binary. 


chan configure $fid -translation binary 


To read from the file, you would then typically use the reaa command, 
specifying the number of bytes of data to read. You could then use the binary 
scan Command, described in Chapter 5, to “unpack” the binary information 
into Tcl variables: 


set data [read $fid 12] 
binary scan $data iiss intl int2 shortl short2 


Conversely, to write binary data to a file, you would typically “pack” the 
values into a binary string with the binary format command, described in 
Chapter 5, and write the string to the file using the puts command. In most 
cases you should use the -nonewiine option to puts to prevent it from 
automatically adding a newline character after the bytes written: 


set data [binary format s3 {3 -7 1}] 
puts -nonewline $fid $data 


11.6.6 Random Access to Files 


File I/O is sequential by default—each gets or reaa command returns the next 
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bytes after the previous gets OF reaa command, and each puts command writes 
its data immediately following the data written by the previous puts 
command. However, you can use the chan seek, chan tell, ANd chan cof 
commands to access files nonsequentially. (Equivalent seer, tei, and cor 
commands are available for compatibility with older versions of Tcl.) 

Each open file has an access position, which is the location in the file 
where the next read or write will occur. When a file is opened, the access 
position is set to the beginning or the end of the file, depending on the 
access mode you specified to open. After each read or write operation the 
access position increments by the number of bytes transferred. You can use 
the chan seek command to change the current access position. In its simplest 
form chan seek takes two arguments, a file identifier and an integer offset 
within the file. For example, the command 


chan seek $f 2000 


changes the access position for the file so that the next read or write will 
start at byte number 2000 in the file. 


Note 


The offset value is defined in terms of bytes, not characters. Thus, it 
may place the access position in the middle of a multibyte character 
sequence. 


chan seek Can also take a third argument that specifies an origin for the offset. 
The third argument must be either start, current, OF ena. start produces the 
same effect as if the argument were omitted: the offset is measured relative 
to the start of the file. current means that the offset is measured relative to the 
file’s current access position, and ena means that the offset is measured 
relative to the end of the file. For example, the following command sets the 
access position to 100 bytes before the end of the file: 


chan seek $f -100 end 


If the origin is current OF ena, the offset may be either positive or negative; for 
start the offset must be positive. 


Note 
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It is possible to seek past the current end of the file, in which case the 
file may contain a hole. Check the documentation for your operating 
system for more information on what this means. 


The chan te11 command returns the current access position (in bytes, not 
characters) for a particular file identifier: 


chan tell $f 
=> 186 


This allows you to record a position and return to it later. 

The chan eof command takes a file identifier as argument and returns o or : to 
indicate whether the most recent gets Or reaa command for the file attempted 
to read past the end of the file: 


chan eof $f 
=> 0 


In most cases you'll use the chan eof command to detect the end of a file 
when using non-blocking channels. See Chapter 12 for more on this. 


11.6.7 Copying File Content 


Section 11.5.3 discussed the fi1e copy command, which duplicates a file on 
disk. The fi1e copy command is easy to use, but it does have its limitations: it 
creates a byte-for-byte duplicate of the original file and works only for on- 
disk files. A more flexible alternative is the chan copy command (or fcopy, for 
compatibility with older versions of Tcl), which allows transformations, 
such as changing the character encoding, and works with any supported Tcl 
channel type, such as pipes and sockets as well as on-disk files. 

In its simplest form, the chan copy command accepts an input channel opened 
for reading and an output channel opened for writing as arguments. The 
input channel is read until an end of file 1s encountered, and the content is 
written to the output channel. Alternatively, you can use the -size option to 
specify a maximum number of bytes to read from the input channel. As an 
example, the following copies the contents of a file, translating from EUC- 
JP to Shift_JIS encoding: 


261 


set input [open SinFile r] 

chan config $input -encoding euc-jp 
set output [open SoutFile wi] 

chan config $output -encoding shiftjis 
chan copy Sinput Soutput 

close $input 

close $output 


By default, the cnan copy command blocks, not returning until the copy is 
complete; its return value is the number of bytes written to the output 
channel. You have the option of specifying a callback with the -commana 
option, in which case the chan copy command returns immediately. The copy 
takes place in the background, and upon completion Tcl invokes the 
callback, appending one or two arguments. The first argument is the number 
of bytes written to the output channel. The second is present only if an error 
took place during the copy, in which case it consists of the error message. 


Note 


The background copy takes place only while Tcl’s event loop is 
running. If the event loop is not already running, you'll need to start it 
with a command such as wwait. Additionally, you should not have any 
channel event handlers, as registered with the chan event OF fileevent 
commands, active during the background copy. Chapter 12 has more 
information on the event loop, the wait command, and channel event 
handlers. 


The following code shows an example of a background copy: 
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proc copyComplete {args} { 
global enter loop 
if {[llength $args] > 1} { 
puts "Error during file copy: [lindex Sargs 1]" 
} else { 
puts -nonewline "Copy completed successfully. " 
} 


puts "[lindex Sargs 0] bytes copied." 
set enter _loop 1 


} 


set input [open $inFile r] 

chan config $input -encoding euc-jp 

set output [open SoutFile w] 

chan config $output -encoding shiftjis 

chan copy $input Soutput -command copyComplete 
vwait enter loop 


# Copy operation has completed at this point 


catch {close $input} 
catch {close $output} 


The copycompiete procedure implements the callback to execute once the file 
copy is complete. If only one argument is passed to it, the copy completed 
successfully; if more than one argument is provided, an error occurred 
during the copy, and the procedure prints the error message to the console. 
After the input and output channels are opened and configured, the chan copy 
command initiates the background copy. The wait command starts the event 
loop; the vwait command waits until the global variable enter icop 18 set 
(which is done during execution of the copycompiete callback script), at which 
point the event loop terminates and the vwait command returns. At this point, 
the two channels are closed. 


11.7 Virtual File Systems 


Starting with Tcl 8.4, Tcl’s file commands support virtual file systems. This 
means that Tcl extensions can add support for other services to appear to Tcl 
as if they were file systems. For example, FTP network file access can 
appear to Tcl commands such as gicb or fiie as if the remote files were 
really local on your hard disk, or files within a ZIP archive can be accessed 
as though they were individual files on the file system. Using such a virtual 
file system makes writing Tcl scripts a lot easier. You merely use the normal 
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file commands in Tcl and let the Tcl extension perform all the difficult work. 
And, if the mapped file system supports it, you can create new files or edit 
existing ones on the mounted virtual file system, even if the underlying data 
is not a file. Some of the most exciting developments in Tcl, Starpacks and 
Starkits in particular, use virtual file systems. See Chapter 14 for more on 
these. 

The tcivts extension provides a set of bindings to virtual file systems that 
you can access from Tcl commands. These include ZIP archives, FTP 
network access, Metakit files (used by Starkits and Starpacks), as well as 
WebDAV and HTTP network protocols. One of the most common uses, 
though, is mounting compressed files as if they were file systems. This 
allows you to browse the contents of a ZIP archive, for example, or read 
individual files from it. 

The following code mounts a ZIP file as if it were under a virtual directory 
named zip within the current working directory: 


puts [pwd] 

=> /Users/ericfj/Documents/tcl 
package require vfs::zip 
vfs::zip::Mount tcl852-srce.zip zip 


This example uses the ZIP file of Tcl 8.5 sources downloaded from 
http: //tcl.sourceforge.net; YOU can use any ZIP files you have handy instead. 
Once it is mounted, you can access a virtual file system as if it were a 
normal file system. For example, to list the top-level files in the Tcl source 
distribution just mounted, you could use a command like the following: 


foreach f [glob zip/tcl8.5.2/*] { 
puts Sf 
} 


In this example, the gic» command returns all files underneath the directory 
zip/tcls.5.2. The zip part comes from where we mounted the virtual file 
system. The tcis.5.2 part comes from the top-level directory inside the ZIP 
file. 


Note 


If the package require command fails, you need to install the tcives 
extension. The easiest way to do this is to download the ActiveTcl 
release, which includes a precompiled version of tcivsrs. You can also 
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download the source code for eaves from 


http://sourceforge.net/projects/tclvfs. 


Once you have mounted virtual file systems, you can use the ves::filesystem 
info Command to get a list of all mounted ones; for example: 


puts [vfs::filesystem info] 
= {/Users/ericfj/Documents/tcl/zip} 


When you’re finished with a virtual file system, use the vés::fi1esystem unmount 
command to unmount it: 


vfs::filesystem unmount zip 


As another example, consider mounting an mx, or Metakit, file as a virtual 
file system. Tcl Starkits and Starpacks are Metakit files. You can download 
a Starkit file, such as tcinttpa.xit (an HTTP server written in Tcl), from sites 
such a nttp://tcl.tk/starkits. This file provides a good example of a Metakit 
file, along with a nice Tcl source code example that shows how to build an 
HTTP (web) server. 

You can access the contents of a Starkit file similarly to a ZIP file; for 
example: 


package require vfs: :mk4 
vfs::mk4::Mount tclhttpd.kit kit 
foreach f [glob kit/*] { 

puts $f 
} 


vfs::filesystem unmount kit 
When you run this script, you'll see output such as the following: 
=> kit/bin 
=> kit/custom 
= kit/htdocs 
=> kit/lib 


=> kit/main.tcl 


See the reference documentation on ves and ves-filesystems for more 
information on how to use virtual file systems. 


11.8 Errors in System Calls 
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Most of the commands described in this chapter invoke calls on the 
operating system, and in many cases the system calls can return errors. This 
can happen, for example, if you invoke open OF file stat on a file that doesn’t 
exist, or if an I/O error occurs in reading a file. The Tcl commands detect 
these system call errors and in most cases return errors themselves. The 
error message identifies the error that occurred: 


open bogus 
@ couldn’t open “bogus”: no such file or directory 


When an error occurs in a system call, Tcl also sets the errorcode global 
variable and the -errorcode key in the return options dictionary to provide 
additional information about the error. The value is typically a three- 
element list, where the first element is the string rostx, the second element is 
a symbolic error name such as enoznt, and the last element is a human- 
readable error message. See Chapter 13 for more information on error 
handling. 
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12. Processes and Interprocess 
Communication 


Tcl provides several commands for dealing with processes. You can create 
new processes with the exec command, or you can create new processes 
with open and then use file I/O commands to communicate with them. Tcl 
also supports interprocess communication via TCP/IP sockets. You can 
access process identifiers with the pia command. You can read and write 
environment variables using the env variable, and you can terminate the 
current process with the exit command. 


12.1 Commands Presented in This Chapter 


This chapter discusses the following commands related to process control 
and interprocess communication: 


xec ?-keepnewline? ?-ignorestderr? ?--? arg ?arg...? 
Executes the command pipeline specified by args using one or more 
subprocesses and returns the pipeline’s standard output or an empty string if 
output is redirected (the trailing newline, if any, is dropped unless - 
keepnewline 18 Specified). I/O redirection and pipes may be specified. If the 
last arg iS «, the pipeline is executed in background and the return value is a 
list of its process IDs. If any process writes to its standard error channel 
and that output is not explicitly redirected, exec raises an error unless the - 
ignorestderr Option 1s specified. 

© exit ?code? 
Terminates a process, returning coae to the parent as the exit status. coae must 
be an integer and defaults to o. 

© open | command ?access? 
Treats command aS a list with the same structure as arguments to exec and 
creates subprocess(es) to execute command(s). Depending on access, it 
creates pipes for writing input to a pipeline and/or reading output from it. 
Returns a file identifier for communicating with the subprocesses. 

* pid ?fileID? 
If riierp 18 omitted, returns the process identifier for the current process. 
Otherwise it returns a list of all the process IDs in the pipeline associated 
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with riterp (which must have been opened using |). 


® socket ?options? host port 


Opens a client-side TCP/IP socket connection to the nost and port indicated, 
returning a channel identifier for the socket connection created. The nost may 
be either a domain-style host name or a numerical IP address. The port may 
be an integer port number (or a service name, where supported and 
understood by the host operating system). See the following sections and the 
reference documentation for a description of the supported options. 


® socket -server command ?0ptions? port 


Opens a TCP/IP server socket for the port, returning the channel identifier of 
the server socket created. The pore may be an integer port number (or a 
service name, where supported and understood by the host operating 
system); a value of o causes the operating system to allocate an unused port 
for the server socket. When a client connects to the server port, Tcl 
automatically creates a new channel to use for communication with that 
client, then invokes the specified commana with three additional arguments: the 
new client communication channel, the client IP address, and the client port 
number. Closing the server channel shuts down the server so that no new 
connections are accepted. See the following sections and the reference 
documentation for a description of the supported options. 
® chan configure channelID ?0ptionName? ?value? 
?optionName value ...? 
fconfigure channelID ?optionName? ?value? 
?optionName value ...? 
Queries or sets the configuration options of the channel channeir. If no 
optionName OF value arguments are supplied, the command returns a dictionary 
of all configuration options and their values. If optionname 18 supplied but no 
value, the command returns the current vaiue of the given option. If one or 
more pairs Of optionnvame and vaiue are supplied, the command sets each of the 
named options to the corresponding value; in this case the return value is an 
empty string. See the following sections and the reference documentation for 
a description of the supported options. Starting with Tcl 8.5, configure 1S 
deprecated in favor of chan configure. 
® chan event channelID event ?script? 
fileevent channelID event ?script? 
Installs the Tcl script script as a file event handler to be called whenever 
channelrp enters the state described by event (which must be either readable or 
writable). Only one such handler may be installed per event per channel at a 
time. If script 18 an empty string, the current handler is deleted. If script is 
omitted, the currently installed script 1s returned (or an empty string if no 
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such handler is installed). Starting with Tcl 8.5, ¢itcevent 18 deprecated in 
favor of chan event. 


® vwait variableName 


Enters the Tcl event loop, and continues to process all events received until 
some event handler sets the value of the variable specified by variabiename. 
At that point, once the event handler that set the variable completes, the wait 
command finally returns. 


12.2 Terminating the Tcl Process with x: 


Invoking the exit command terminates the process in which the command 
was executed. exit takes an optional integer argument. If this argument is 
provided, it is used as the exit status to return to the parent process. o 
indicates a normal exit, and nonzero values correspond to abnormal exits; 
values other than o and : are rare. If no argument 1s given to exit, 1t exits with 
a status of o. Since exit terminates the process, it doesn’t have any return 
value. 


12.3 Invoking Subprocesses with ex. 


The exec command creates one or more subprocesses and waits until they 
complete before returning. For example, 


exec rm main.o 


executes rm as a subprocess, passes it the argument main.o, and returns after rm 
completes. The arguments to exec are similar to what you would type as a 
command line to a shell program such as sh or csn. The first argument to exec 
is the name of a program to execute, and each additional argument forms one 
argument to that subprocess. 


Note 


The preceding example is for illustration only. If your goal is to delete 
a file, copy a file, list the contents of a directory, etc., Tcl’s built-in 
commands such as file de1ete are a better choice for two reasons. First, 
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by avoiding platform-specific commands, such as rm on Unix and ae1 on 
Windows, you can run your script on any operating system where Tel is 
supported. Second, the built-in Tcl command deletes the file by 
invoking a system function call, rather than incurring the expense of 
starting another process. 


To execute a subprocess, exec looks for an executable file with a name equal 
tO exec’s first argument. If the name contains a / or starts with ~, exec checks 
the single file indicated by the name. Otherwise exec checks each of the 
directories in the ears environment variable to see if the command name 
refers to an executable file in that directory. exec uses the first executable 
that it finds. 

exec COllects all of the information written to standard output by the 
subprocess and returns that information as its result, as in the following 
example: 


exec we /usr/include/stdio.h 
=> 71 230 =1732 /usr/include/stdio.h 


If the last character of output is a newline, exec removes it. This behavior 
may seem strange, but it makes exec consistent with other Tcl commands, 
which don’t normally terminate the last line of the result; you can retain the 
newline by specifying -xcepnewline aS the first argument to exec. 

exec Supports I/O redirection in a fashion similar to the Unix shells. For 
example, if one of the arguments to exec 18 >#00, Output from the process is 
placed in the file 0.0 instead of returning to Tcl as exec’s result. In this case 
exec § result will be an empty string. Many other forms of input and output 
redirection are supported as well, as listed in Table 12.1. 


Table 12.1 Subprocess I/O Redirection Syntax 
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Redirection Interpretation 


>file Redirects standard output to file, overwriting its previous contents 

>>file Appends standard output to file instead of replacing file 

>@fileID Redirects standard output to the open file whose identifier (returned 
by open) is fileID 

2>file Redirects standard error to file 

2>@fileID Redirects standard error to the open file whose identifier (returned by 
open) is fileID 

2>@1 Redirects standard error from all programs to the command result 

>&file Redirects both standard output and standard error to file, overwrit- 
ing its previous contents 

>>&file Redirects both standard output and standard error to file, append- 
ing to its previous contents 

>&fileID Redirects both standard output and standard error to the open file 
whose identifier (returned by open) is fileID 

<file Causes standard input to be taken from file 

<<value Passes value (an immediate value) to the subprocess as its standard 
input 

<®fileID Causes standard input to be taken from the open file whose identifier 
is filerIp 


| Pipes standard output of the preceding program to standard input of 
the following program 


| & Pipes both standard output and standard error of the preceding pro- 
gram to standard input of the following program 


Note 


The eriiezp Syntax 1s not supported on Windows. Additionally, not all 
Windows applications work well with the exec command. 


In each of the cases shown in the table, rite or vaiue OF rilerp may follow the 
redirection symbol in a single argument, or it may be in a separate argument. 
As an example of using redirection, consider the following command: 


exec cat << "test data" > foo 


This command overwrites the file soo with the string test data. The string is 
passed to cat as its standard input; cat copies the string to its standard output, 
which has been redirected to file soo. Ifno input redirection is specified, the 
subprocess inherits the standard input channel from the Tcl application; if no 
output redirection is specified, the standard output from the subprocess is 
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returned as exec’s result. 
You can also invoke a pipeline of processes instead of a single process, as 
in the following example: 


exec grep #include tcIInt.h | we 
> 8 25 212 


The grep program extracts all the lines containing the string ¢inciuae from the 
file tcitnt.n. These lines are then piped to the we program, which computes 
the number of lines, words, and characters in the grep output and prints this 
information on its standard output. The we output is returned as the result of 
If the last argument to exec iS «, the subprocess(es) will be executed in 
background. exec returns immediately, without waiting for the subprocesses 
to complete. It returns a list containing the process identifiers for all of the 
processes in the pipeline; standard output and standard error from the 
subprocesses go to the standard output and standard error of the Tcl 
application unless redirected. 

The exec command raises an error if a subprocess is suspended or exits 
abnormally (for example, it is killed or returns a nonzero exit status). exec 
also raises an error if a subprocess generates output on its standard error 
channel and standard error was not redirected; you can suppress this 
condition by providing the -ignorestderr Option tO exec. The error message 
consists of the output generated by the last subprocess (unless it was 
redirected with >), followed by an error message for each process that 
exited abnormally, followed by the information generated on standard error 
by the processes, if any. In addition, exec sets the errorcode variable and the - 
errorcode key 1n the return options dictionary to hold information about the 
last process that terminated abnormally, if any (see Section 13.2 and the 
reference documentation for details). 


Note 


Many Unix programs are careless about the exit status that they return. 
If you invoke such a program with exec and it accidentally returns a 
nonzero status, the exec command generates a false error. To prevent 
these errors from aborting your scripts, invoke exec inside a catch 
command as described in Chapter 13. 
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Although exec’s features are similar to those of the Unix shells, there is one 
important difference: exec does not perform any file name expansion. For 
example, suppose you invoke the following command with the goal of 
removing all .. files in the current directory: 


exec rm *.0 
@ rm: *.o nonexistent 


rm TeCeiVes *.o aS its argument and exits with an error when it cannot find a 
file by this name. If you want file name expansion to occur, you can use the 
glob Command to get it, but not in the obvious way. For example, the 
following command will not work: 


exec rm [glob *.o] 
@ rm: a.o b.o nonexistent 


This fails because the list of file names that gio» returns is passed to rm as a 
single argument. If, for example, there exist two .o files, 2.o and b.o, rm’S 
argument will be a.o ».o; since there is no file by that name, xm returns an 
error. The recommended way to handle this situation is to use Tcl’s 
argument expansion syntax to provide the list elements as separate 
arguments: 


exec rm {*}[glob *.tmp] 


As discussed in Section 2.8, versions of Tcl prior to 8.5 used the evai 
command to similar effect: 


eval exec rm [glob *.o] 


12.4 I/O to and from a Command Pipeline 


You can also create subprocesses using the open command; once you’ve done 
this, you can use commands like gets and puts to interact with the pipeline. 
Here are two simple examples: 


set fl [open {|sort -k 2 > newfile.txt} w] 
set f2 [open |prog r+] 


If the first character of the “file name” passed to open is the pipe symbol |, 
the argument isn’t really a file name at all. Instead, it specifies a command 
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pipeline. The remainder of the argument after the | is treated as a list whose 
elements have exactly the same meaning as the arguments to the exec 
command. open creates a pipeline of subprocesses just as for exec, and it 
returns an identifier that you can use to transfer data to and from the 
pipeline. In the first example the pipeline is opened for writing, so a pipe is 
used for standard input to the Unix sort program, and you can invoke puts to 
write data on that pipe; the output from sort is redirected to a file named 
newfile.txt. The second example opens a pipeline for both reading and 
writing, so separate pipes are created for prog’s standard input and standard 
output. Commands like puts can be used to write data to prog, and commands 
like gets and reaa can be used to read the output from prog. In general, any of 
the I/O-related commands discussed in Chapter 11 can be used to interact 
with a pipeline channel. 


Note 


When writing data to a pipeline, don’t forget that output is buffered. It 
probably will not be sent to the child process until you invoke the chan 
flush command to force the buffered data to be written. You can change 
the channel’s buffering using the chan configure command, as discussed 
in Section 12.5.2. 


When you close a file identifier that corresponds to a command pipeline, the 
close command flushes any buffered output to the pipeline, closes the pipes 
leading to and from the pipeline, if any, and waits for all of the processes in 
the pipeline to exit. If any of the processes exits abnormally, ciose returns an 
error in the same way @aS exec. 


12.5 Configuring Channel Options 


As discussed in Chapter 11, the chan configure command sets channel options 
(as does the fconfigure command, for compatibility with older versions of 
Tcl). Chapter 11 discussed the use of this command to configure character 
encoding and end-of-line translations for file I/O. You can use chan configure 
to configure these settings for command pipelines and socket channels as 
well. This section describes some additional chan configure settings of 
particular interest to command pipelines and socket channels. 
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12.5.1 Channel Blocking Mode 


By default, when you call gets or reaa on a channel, Tcl blocks until data is 
available to read. gets blocks until it has received a complete line of data, 
and reaa blocks until it has read the specified number of characters or it 
encounters the end of file. Similarly, the pues command buffers the output, 
and if the buffers fill, puts blocks until the output gets sent. This is called 
blocking mode. Blocking forms the proper option for many uses and 
simplifies programming. For example, your program may read in the 
contents of a file, process the data, and output the results. Blocking works 
fine in most cases for this usage. 

However, if your application opens a process pipeline or network socket, 
data might arrive at sporadic intervals, and blocking I/O commands could 
pause the process for an indeterminate amount of time. If your application 
has a graphical user interface, Tcl can’t service key presses, button clicks, 
window refreshes, and other interactions while an I/O command 1s blocked; 
your application is frozen until the I/O command finally returns. In these 
types of applications, using non-blocking channels is usually preferable. 
Similarly, network servers usually need to run in non-blocking mode to be 
able to handle multiple clients at once. A server cannot wait until one client 
sends data before servicing the remaining clients, especially if the client the 
server waits for is not currently sending data; other clients are then starved 
for service in blocking mode. 

The -biccking option Of chan configure Indicates whether or not the channel is 
configured for blocking mode. You can change the option by providing a 
Boolean value. For example, to set a channel to non-blocking mode: 


chan configure $chan -blocking 0 


If you do not pass a value to chan configure, the command returns the current 
value for an option. For example, to determine if a channel is set to blocking 
mode, issue the following command: 


chan configure $socketid -blocking 


When a channel is set to non-blocking mode, a reaa on the channel returns all 
characters available on the channel, up to the maximum number of 
characters requested, if specified. A gets on a non-blocking channel returns 
characters only if there is a complete line to read. If there is not a complete 
line, gets does not consume any characters. If you didn’t provide a variable 
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name as an argument, gets returns an empty string; if you did provide a 
variable name, gets sets the variable to an empty string and returns -1. This 
is actually the same result that gets provides in the case of an end-of-file 
condition, so Tcl provides two additional commands to distinguish between 
these cases. 

The chan eof Command returns : if the last input operation on a channel 
encounters an end-of-file condition, and o otherwise. The chan pbiockea 
command returns : if the most recent input operation on a channel returns 
less information than requested because all available input is exhausted, and 
o Otherwise. (The cor and fbiockea commands are also available for 
compatibility with older versions of Tcl.) 


12.5.2 Channel Buffering Mode 


Tcl automatically buffers all channel I/O for efficiency. The channel’s input 
and output buffers have the same size, typically defaulting to 4KB. You can 
view or change the buffer size for a channel using the -burfersize option of 
chan configure. YOU can change the buffer size to any value from 1 byte to 
1MB currently; values requested outside of this range are appropriately 
adjusted to the minimum or maximum supported. 

The buffer size is the only configurable parameter for input buffering. If 
there is not sufficient data in an input buffer to fulfill a read request on a 
channel, Tcl reads as much data as is currently available from the underlying 
source (e.g., file, pipeline, socket, etc.) up to the maximum buffer size. 

The behavior of output buffering on a channel is also controlled by the - 
buffering Option tO chan configure, Which determines when Tcl should 
automatically flush a channel. The -vurfering option supports values of none 
(flush on every output), 1ine (flush after every line), or ¢u11 (flush when the 
buffer fills or the script calls the chan fiusn command). The -purfering option 
defaults to su11 except for channels that connects to “terminal-like” devices; 
for these channels the initial setting 1s 1ine. Additionally, stain and staout are 
initially set to 1ine, and staerr 18 Set tO none. 


12.6 Event-Driven Channel Interaction 


The default blocking behavior of channels described in Section 12.5.1 is 
usually not a problem for many applications. If the application is driven 
from the console rather than a graphical user interface, or if the application 
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doesn’t interact with the user at all, it usually doesn’t matter if an I/O 
operation on the channel is blocked for seconds or even minutes at a time. 
On the other hand, if the application must present a responsive user 
interface, must interact with several channels simultaneously, or needs to 
perform other operations in parallel with the channel access, having the 
entire application freeze while an I/O operation blocks is unacceptable. 
Changing the channels to non-blocking helps to address this issue. But even 
then, attempts to read from the channels might return with no data if there is 
no data available from the underlying source. Repeatedly attempting to read 
from the channel until data is available would waste processing time. 

Many other languages use threads to address this issue of interacting with 
blocking channels. If one thread is blocking by an I/O operation, other 
threads are free to continue execution. Multithreaded programs have their 
own issues, though, such as managing resource contention and 
synchronization. Although Tcl does have a threaa extension, which exposes 
multithreaded programming at the scripting level (see Appendix B), 
traditionally Tcl has taken a different approach: event-driven programming. 

In an event-driven programming model, an application registers scripts as 
event handlers that are triggered in response to various events that take 
place during its execution. Chapter 1 has already introduced the concept of 
event handlers to implement widget action in response to user interaction. 
Using these event bindings in Tk to associate actions with user interaction 
and other windowing events is further discussed in Chapter 17 and Chapter 
22. Tcl also supports timer-related events through a command called after, 
which is discussed in Chapter 15. 

Tcl supports another set of bindings to respond to events that take place on 
channels, which are referred to as file events or channel events. For 
example, you can register a script to be invoked whenever data arrives ona 
pipeline or socket channel. If your application needs to interact with 
multiple channels, each can have its own file event handlers to process 
those events in whatever way is appropriate. At the same time, Tcl can also 
monitor windowing and timer events and invoke any event handlers 
associated with those events as well. 


12.6.1 Entering the Tcl Event Loop with wwait 


To be able to detect events occurring and to invoke any registered handlers, 
Tcl must be in its event Joop. When an application is invoked with the wisn 
interpreter or has the Tk package loaded, it automatically enters the event 
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loop after executing all of the commands in the script file. For applications 
that don’t use Tk, you must explicitly enter the Tcl event loop with a 
command. 

Typically the wait command is used to invoke the event loop. wait accepts 
one argument, the name of a global or persistent namespace variable, as in 


vwait enter_loop 


The vwait command enters the Tcl event loop and continues to process all 
events received until some event handler sets the value of the variable 
specified (enter ioop 1n this example). At that point, once the event handler 
that set the variable completes, the vwait command finally returns. 


12.6.2 Registering File Event Handlers 


You register a file event handler with the chan event command. (The fiteevent 
command is also available for compatibility with older versions of Tcl.) In 
addition to specifying the channel identifier and a script to invoke when the 
event occurs, you indicate whether you are registering a handler for a 
readable or writable event on the channel. For example, the following 
arranges to call the command reaa.ine whenever there is data to read on the 
channel whose identifier is stored in the variable pipe: 


chan event $pipe readable ReadLine 


You can create at most one readable and one writable event handler for a 
given channel. Invoking chan event to install an event handler of a given type 
on a channel replaces any existing handler of that same type on the channel. 
If you omit the script argument, chan event returns the currently installed 
handler, if any. 

The Tcl event loop must be active for Tcl to be able to detect and handle file 
events. Additionally, you normally should use the chan configure command to 
place the channel in non-blocking mode. Otherwise, the handler could block 
when attempting to read from or write to the channel. 

A channel is considered to be writable if at least 1 byte of data can be 
written to the underlying file or device without blocking, or if an error 
condition is present on the underlying file or device. Writable file event 
handlers are used most frequently to detect when a client socket opened in 
asynchronous mode becomes connected or if the connection fails. This is 
discussed in Section 12.9. 
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A channel is considered to be readable if there is unread data available on 
the underlying device. A channel is also considered to be readable if there 
is unread data in an input buffer, except in the special case where the most 
recent attempt to read from the channel was a gers call that could not find a 
complete line in the input buffer. This feature allows a file to be read a line 
at a time in non-blocking mode using events. A channel is also considered to 
be readable if an end-of-file or error condition is present on the underlying 
file or device. 


Note 


It is important for an event handler to check for these conditions and 
handle them appropriately. For example, if there is no special check 
for end of file, an infinite loop may occur when the handler reads no 
data, returns, and is invoked again immediately. 


The following script is a simple example of using file events to process the 


output of a process pipeline. It illustrates several features of handling 
asynchronous communication on a channel in a safe and robust manner. 
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set fid [open "| du /usr " r] 
chan configure $fid -blocking 0 
chan event $fid readable [list ReadLine $fid] 


proc ReadLine {fid} { 
global done 
if {[catch {gets $fid line} len] || [chan eof $fid]} { 


# The last gets encountered EOF or we had an 
# abnormal termination. 


catch {close $fid} 
puts stderr "Channel closed" 
set done 1 
return 
} elseif {$len >= 0} { 


# We read a complete line, otherwise gets would have 
# read no characters and returned -1. 


puts "Read line: $line" 
# We reach this point if there wasn't a complete line 


to read. Simply return to the event loop to wait 
# for more data. 


th 


} 


vwait done 


The first line of the script opens a process pipeline for read access. In this 
case, it starts the Unix av command, which recursively reports disk usage for 
a directory. The script then configures the channel for non-blocking access. 
If this were a bidirectional channel where you were writing to the channel 
to send data to the process pipeline, you might also want to configure the 
buffering on the channel, perhaps to 1ine mode so that each line would be 
written to the pipe immediately. 

The script then registers a file event handler to invoke whenever data is 
available to read on the channel. In this case, the script is a well-formed list 
consisting of the reaaiine command and the channel identifier as an argument. 
For a simple handler such as this, we could have just quoted the handler 
script in double quotes to allow substitution of the variable, because 
channel identifiers don’t include whitespace or other special characters. 
However, if we had tried to pass other variable values as arguments that 
could be arbitrary strings, simple double quoting could produce malformed 
commands. When registering callbacks, it’s safest to use techniques such as 
the 1ist command to ensure that the resulting script argument is a well- 
formed Tcl command. After defining the event handler procedure, the script 
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finally executes vwait to enter the event loop. Tcl continues to process events 
in the event loop until a handler sets the variable done to any value, at which 
point the wait command returns and the script terminates. 

The reaatine handler itself first tries to read a complete line of data from the 
channel. The gets command could fail if the channel shuts down abnormally, 
so it’s safest to execute it in a catch Statement. If catch reports an error, or if 
an end-of-file condition is detected on the channel, we’ve read all data 
possible from the channel. The handler closes the channel (using a catch to 
silently discard any errors), sets the global variable aone to 1, and returns to 
the event loop. Because the wait command is waiting for aone to be set, this 
terminates the event loop. 

On the other hand, if an error or end of file is not detected, reaaiine checks 
the return value of the gets command. If it was -1, gets was not able to read a 
complete line, and so it consumed no characters from the channel. (The 
other situation in which gets would return -1, an end of file, was tested for 
previously.) In this case, readiine simply returns to the event loop to wait for 
more data to arrive. But if gets was able to read a complete line, the 
characters read are now contained in the variable iine and can be processed 
as desired. 


12.7 Process IDs 


Tcl provides three ways to access process identifiers. First, invoking a 
pipeline in background using exec returns a list containing the process 
identifiers for all of the subprocesses in the pipeline. You can use these 
identifiers, for example, if you wish to kill the processes. Second, you can 
invoke the pia command with no arguments and it returns the process 
identifier for the current process. Third, you can invoke pia with a file 
identifier as an argument, as in the following example: 


set £ [open {| tbl | ditroff -ms} w] 
pid $f 
> 7189 7190 
If there is a pipeline corresponding to the open file, as in the example, the 
pia command returns a list of identifiers for the processes in the pipeline. 


12.8 Environment Variables 
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As mentioned in Chapter 3, the global array variable env contains all of the 
environment variables as elements, where the name of the element in env 
corresponds to the name of the environment variable. If you modify the env 
array, the changes are reflected in the process’s environment variables and 
the new values are also passed to any child process created with exec or 


open. 


12.9 TCP/IP Socket Communication 


Sockets link applications using network protocols such as TCP/IP, the 
Internet’s transmission control protocol/Internet protocol. Because socket- 
based networking is standardized, Tcl’s support for sockets enables another 
avenue for integrating your Tcl applications with other, non-Tcl, 
applications. 

Sockets are identified by a host name or IP address and a port number. A 
port 1s sort of like a channel number on a television. The port numbers for 
most network services, such as HTTP, are standardized (port 80 for HTTP, 
for example). Normally, port numbers under 1024 are restricted for use by 
privileged applications. In addition, many port numbers between 1024 and 
49151 inclusive are standardized, such as 6000 and 6001 for the X Window 
System, and are often registered with the Internet Assigned Numbers 
Authority ANA). Port numbers higher than this are not standardized but 
may be in use by other applications installed on your system. On Unix 
systems, look at the file /etc/services for a listing of predefined port numbers. 
Unlike most systems, Tcl’s communications channels are driven by events. 
Typical servers written in other languages either fork (clone) the current 
process to handle an incoming connection or spawn a new thread. Tel 
servers, on the other hand, typically use event handler procedures to process 
network requests. See Section 12.6 for more on this subject. 


12.9.1 Creating Client Communication Sockets 
To create a socket, use the socket command. You can use this command to 
create a socket either for a client application to connect to a server, or for a 


server application that awaits client requests. To create a client socket you 
need to provide the host name or IP address and port number as arguments: 
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set sockid [socket localhost 12345] 


This command opens a client-side socket on the local system on port 12345. 
The returned channel identifier gets stored in sockia. 


Note 


Use iocainost to refer to the computer where your Tcl program executes. 


With client sockets, you can use the -myaaar option to specify the Internet 
address of a network interface on the local system to use, which is handy for 
systems with more than one network interface (or network adapter card). 
Use -myport to specify the client-side port, if needed; if this option is omitted, 
the client’s port number is chosen at random by the system software, which 
is typical for client-side sockets. 

Once you have established the socket connection, you can then configure the 
channel and interact with it using I/O commands just as with process 
pipelines. For example, you could configure it to non-blocking mode and 
register a file event handler to read data from the socket as it arrives, just as 
in the process pipeline example shown in Section 12.6.2. By default, socket 
channels are configured for blocking and full buffering. The -transiation 
defaults to {auto cris} and the -encoding defaults to the system encoding. See 
Section 11.6 for more information on these settings and using the chan 
configure Command to change them. 

For a socket channel, the chan configure Command supports two additional 
read-only options to report information about the socket connection. The 
value of the -sockname 18 a three-element list consisting of the IP address, the 
host name, and the port number for the socket. The value of the -peername 
option contains a three-element list with the same information for the peer 
socket. 

By default, the socket command doesn’t return until the socket connection is 
established. You can also specify -async to create a connection 
asynchronously. This means the sockee command returns before the 
connection has been established. If the socket 1s configured for blocking 
mode, the next gets, read, OF chan flush Command waits until the socket is 
connected. If the socket is not in blocking mode, the next gets, reaa, OF chan 
flush returns immediately, and a subsequent call to chan vicckea WOuld return 
1. Any error establishing the socket connection is reflected as an error when 
these commands are invoked on the channel. You can use the chan event 
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command to register a writable event handler to detect when the connection 
has been established; client sockets opened in asynchronous mode become 
writable When they become connected or if the connection fails. You can then 
test for the presence of the -peername option in the channel’s configuration to 
determine if the connection was successful, as shown here: 


proc connected {fid} { 


# Remove the writable event handler to prevent it 
# from being invoked again. 


chan event $fid writable {} 


# Test for the existence of -peername in the channel 
# configuration to see if the connection was successful. 


if {[dict exists [chan configure $fid] -peername]} { 
# We’re connected. Do whatever you like. 

} else { 
# We’re not connected. Clean up and report the 
# situation however you like. 


} 


set fid [socket -asyne Shost $port] 
chan event $fid writable [list connected $fid] 


12.9.2 Creating Server Sockets 


To create a server socket, call socket with the -server option: 


socket -server command ?options? port 


This command establishes a server socket, also known as a listening 
socket, on the current host at the given port number. You can also pass a 
service name in place of a port number, whose value is dependent on your 
operating system. For systems with multiple network interfaces, you might 
also find the -myaaar option useful to specify the host name or IP address of a 
specific network interface to use; otherwise the server socket is bound so 
that it can accept connections from any interface. 

When the server socket detects a client connection, Tcl creates a channel for 
reading and writing to the client and calls the commana you provided with 
three additional arguments: the new socket identifier, the client’s address, 
and the client’s port number. (Tcl’s event loop must be running for the server 
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socket to detect connection requests.) Once the client is connected, you can 
use normal channel commands, such as those described in Section 12.9.1, to 
configure the channel and communicate with the client. Because each client 
connection is assigned a unique socket channel identifier, the server can 
manage multiple client connections simultaneously. You can use arrays, 
dictionaries, or other data structures to store information related to each 
client; the socket’s channel identifier makes an excellent unique key in this 
case. 

The following script shows a complete implementation of a simple 
multiclient echo server: 


set listen [socket -server ClientConnect 9001] 


proc ClientConnect {sock host port} { 
chan configure $sock -buffering line -blocking 0 
chan event $sock readable [list ReadLine $sock] 
SendMessage $sock "Connected to Echo server" 


} 


proc ReadLine {sock} { 
if {[catch {gets $sock line} len] || [eof $sock]} { 
catch {close $sock} 
} elseif {$len >= 0} { 
EchoLine $sock $line 
} 


} 


proc EchoLine {sock line} { 
global forever 
switch -nocase -- $line { 
exit { 
SendMessage $sock "Killing Echo server" 
catch {close $sock} 
set forever 1 
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} 
quit { 
SendMessage $sock \ 
"Closing connection to Echo server" 
catch {close $sock} 


} 


default { 
SendMessage $sock $line 
} 


} 


proc SendMessage {sock msg} { 
if {[catch {puts $sock $msg} error]} { 
puts stderr "Error writing to socket: $error" 
catch {close $sock} 


} 


vwait forever 
catch {close $listen} 


The script creates a listening socket on port 9001 of the local system. 
Whenever a client connection request is detected, Tcl calls the ciientconnect 
procedure, which configures the communication channel with the client, 
registers a readable file event handler for the channel, and then sends a 
connection confirmation message to the client. Note that the socket’s channel 
identifier is included as an argument to the reaanine procedure registered as 
the event handler. As a result, the reaazine procedure knows which channel 
has data available to read when it is invoked, and we can use the same 
procedure for all channels. 

The readhine procedure is very similar to the event handler presented in 
Section 12.6.2 for process pipeline channels. It closes the communication 
socket if the client disconnects or an error occurs while reading from the 
channel. Otherwise, it checks whether it read a complete line from the 
channel, and if so it passes the line read off to the echotine procedure for 
processing; otherwise, reaatine returns to the event loop to wait for more 
data to arrive on the channel. 

The echotine procedure checks to see if the line just read is a special control 
message. A line consisting of just the string exit terminates the echo server 
by setting the wait variable and returning. A line consisting of quit causes 
the echo server to send an acknowledgment to the client and closes the 
client’s socket channel, disconnecting the client. Any other line received is 
simply echoed back to the client. 

The senamessage procedure is a helper procedure to send messages to a client 
safely. If an error is detected sending the message, the socket is dead. The 
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procedure logs a message to the standard error channel, then closes the 
socket channel. 


Note 


The extensive use of catch commands in this example is a good practice 
when writing multiclient servers. You don’t want a communication 
glitch with one client to bring down the entire server. Use the catcn 
command to guard against errors when opening channels and in all I/O 
operations with the channels. 


12.10 Sending Commands to Tcl Programs 


TCP/IP sockets let you send data between applications, and the Tk package 
also allows you to send commands directly from one Tk-based application 
to another on most Unix systems. With the sena command, any Tk application 
can invoke arbitrary Tcl scripts in any other Tk application on the display; 
these commands can both retrieve information and take actions that modify 
the state of the target application. 


Note 


The sena command is part of Tk, not the base Tcl language. 
The sena command is built on top of data-transfer facilities in the X Window 


System, used on most Unix systems for graphics. sena is not available on 
systems that don’t use the X Window System. 


Note 


In most cases, you should use sockets to pass data between 
applications. Not only are sockets safer, but Tcl’s sockets work on 
multiple operating systems. 
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12.10.1 Basics of sena 


To use sena, all you have to do is give the name of an application and a Tcl 
script to execute in the application. For example, consider the following 
command: 


send myapp {selectLine 200} 


The first argument to sena 1s the name of the target application, and the 
second argument is a Tcl script to execute in that application. Tk locates the 
named application, forwards the script to that application, and arranges for 
the script to be executed in the application’s interpreter. The result or error 
generated by the script is passed back to the originating application and 
returned by the sena command. 

send 18 Synchronous: it doesn’t complete until the script has been executed in 
the remote application and the result has been returned. sena defers the 
processing of X events while it waits for the remote application to respond, 
so the application does not respond to its user interface during this time. 
After the sena command completes and the application returns to normal 
event processing, any waiting events are processed. A sending application 
will respond to sena requests from other applications while waiting for its 
OWN sena to complete. This means, for example, that the target of the sena can 
send a command back to the initiator while processing the script, without 
danger of deadlock. In addition, you can use the -async option with sena to tell 
the sena command to work asynchronously and not wait for a response to the 
commands sent. 

One of the most common uses of sena 1s to try simple experiments in Tk 
applications that are already running, such as changing a color or modifying 
the command associated with a button. Most Tk applications don’t present 
an interface for typing Tcl commands directly to the application. However, 
you can always issue commands to such applications by starting an 
interactive wisn application and then invoking sena. For example, the 
following command changes the background color of a particular window in 
an application named scan: 


send scan {.menubar.file configure -bg blue} 
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12.10.2 Application Names 


To send to an application, you have to know its name. Each application on 
the display has a unique name, which it can choose in any way it pleases as 
long as it is unique. In many cases the application name is just the name of 
the program that created the application. For example, wisn uses the 
application name wisn by default; or, if it is running under the control of a 
script file, it uses the name of the script file as its application name. In 
programs like editors that are associated with a file or object, the 
application name typically has two parts: the name of the application and 
the name of the file or object on which it is operating. For example, if an 
editor named m 1s displaying a file named tx.n, the application’s name is 
likely to be mx tx.n. 

If an application requests a name that is already in use, Tk adds a number to 
the end of the new name to keep it from conflicting with the existing name. 
For example, if you start up wisn twice on the same display, the first instance 
will have the name wisn and the second instance will have the name wisn #2. 
Similarly, 1f you open a second editor window on the same file, it will end 
up with a name like mx tx.n #2. 

Tk provides three commands that return information about the names of 
applications. First, the command 


winfo name . 
=> wish #2 


returns the name of the invoking application. Second, the command 


winfo interps 
=> wish {wish #2} {mx tk.h} 


returns a list whose elements are the names of all the applications defined 
on the display. Third, the command 


selection get APPLICATION 


returns the name of the Tk application that currently owns the selection; if no 
Tk application currently owns the selection, the command generates an 
error. 


Note 
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Use the +x appname command to change an application name. 


Use the -aispiayor option to specify a different X Window display. Pass the 
path to a window that Tk can then use to identify the display. 


12.10.3 Security Issues with sena 


The sena command is potentially a major security loophole. Any application 
that uses your display can send scripts to any Tk application on that display, 
and the scripts can use the full power of Tcl to read and write your files or 
invoke subprocesses with the authority of your account. Ultimately this 
security problem must be solved in the X display server, since even 
applications that don’t use Tk can be tricked into abusing your account by 
sufficiently sophisticated applications on the same display. However, 
without Tk it is relatively difficult to create invasive applications; with Tk 
and sena it is trivial. 

You can protect yourself fairly well if you employ a key-based protection 
scheme for your display like xautn instead of a host-based scheme like xnost. 
xauth generates an obscure authorization string and tells the server not to 
allow an application to use the display unless it can produce the string. 
Typically the string is stored in a file that can be read only by a particular 
user, So this restricts use of the display to the one user. 

In order to provide at least a small amount of security, Tk checks the access 
control being used by the server and rejects incoming sends unless xnost- 
style access control is enabled (that is, only certain hosts can establish 
connections) and the list of enabled hosts is empty. This means that 
applications cannot connect to your server unless they use some other form 
of authorization such as that provided by «auth. 
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13. Errors and Exceptions 


A Tcl command can return errors for a variety of reasons, such as when it 
doesn’t receive the right number of arguments, or if the arguments have the 
wrong form, or because some other problem occurs in executing the 
command, such as an error in a system call for file I/O. In most cases errors 
represent severe problems that make it impossible for the application to 
complete the script it is processing. Tcl’s error facilities are intended to 
make it easy for the application to unwind the work in progress and display 
an error message to the user that indicates what went wrong. Presumably the 
user will fix the problem and retry the operation. 

Errors are just one example of a more general phenomenon called 
exceptions. Exceptions are events that cause scripts to be aborted; they 
include the preak, continue, aNd return Commands as well as errors. Tcl allows 
exceptions to be “caught” by scripts so that only part of the work in progress 
is unwound. After catching an exception, the script can ignore it or take 
steps to recover from it. If the script can’t recover, it can reissue the 
exception. 


13.1 Commands Presented in This Chapter 


The following Tcl commands are related to exceptions: 
° catch command ?returnVar? ?optionsVar? 
Evaluates commana aS a Tcl script and returns an integer code that identifies 
the completion status of the command. If returnvar is specified, it gives the 
name of a variable that will be set to the return value or error message 
generated by commana. If optionsvar 18 specified, it gives the name of a variable 
that will be set to the return options dictionary. 
® error message ?info? ?code? 
Generates an error with message aS the error message. If inro 1s specified and 
is not an empty string, it is used to initialize the errormfo variable. If coae is 
specified, it is stored in the errorcode variable. 
® return ?option value ...? ?result? 
Causes the current procedure to return an exceptional condition. If used, - 
code Specifies the return condition and its value must be ox, error, return, break, 


continue, Or an integer. The -errorinfo option may be used to specify a starting 
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value for the errortnfo variable, and -errorcoae may be used to specify a value 
for the errorcoae variable. resuie gives the return value or error message 
associated with the return; it defaults to an empty string. In support of 
constructing advanced, custom control structures, you can also provide any 
number of option value pairs, with arbitrary option names, which become 
entries in the return options dictionary. Also, you can include an explicit - 
options argument, whose value must be a valid dictionary, the entries of 
which become additional option vaiue pairs in the return options dictionary. 
® interp bgerror path ?cmdPrefix? 

Registers cmaprerix aS the background error handler for the interpreter 
specified by patn. The cmaprerix 18 a command name optionally followed by 
any number of arguments. When a background error occurs, the command is 
invoked with the specified arguments and two additional ones: an error 
message and a return options dictionary. If cmaprerix 18 not provided, interp 
pgerror returns the command prefix currently registered for the interpreter. 


13.2 What Happens after an Error? 


When a Tcl error occurs, the Tcl interpreter aborts execution of the current 
command and raises an error condition. If the command 1s part of a larger 
script, the error condition also aborts the script execution. If the error 
occurs while a Tcl procedure is executing, the procedure 1s aborted, along 
with the procedure that called it, and so on until all the active procedures 
have aborted. After all Tcl activity has been unwound in this way, control 
eventually returns to the application executing the Tcl code, along with an 
indication that an error occurred and a message describing the error. It is up 
to the application to decide how to handle this situation, but most interactive 
applications, such as tcish running in interactive mode, display the error 
message for the user and continue processing user input. In a batch-oriented 
application, such as when tcisn 18 invoked with the name of a script file to 
execute, applications often print the error message to the console and exit. 
For example, consider the following script, which is intended to sum the 
elements of a list: 


set list {44 16 123 98 57} 
set sum 0 
foreach el $list { 
set sum [expr {$sum+Selement }] 
} 


@ can’t read "element": no such variable 
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This script is incorrect because there is no variable e1ement: the variable 
name eciement 1n the expr command should have been -: to match the loop 
variable for the foreach command. When the script is executed, an error 
occurs as Tcl parses the expr command: Tcl attempts to substitute the value 
of variable cicment but can’t find a variable by that name, so it signals an 
error. This error indication is returned to the foreacn command, which 
invoked the Tcl interpreter to evaluate the loop body. When foreach sees that 
an error has occurred, it aborts its loop and returns the same error 
indication as its own result. This in turn aborts the overall script. The error 
message 


can't read "element": no such variable 


is returned along with the error condition, which is displayed for the user. 

In many cases the error message provides enough information for you to fix 
the problem. However, if the error occurred in a deeply nested set of 
procedure calls, you might not be able to figure out where it occurred from 
the message alone. To help pinpoint the location of the error, Tcl creates a 
stack trace as it unwinds the commands that were in progress, and it stores 
the stack trace in the global variable errortnto. The stack trace describes 
each of the nested calls to the Tcl interpreter. For example, after the 
preceding error, errorinfo contains the following value: 


can’t read "element": no such variable 
while executing 
"expr {$sum+$element }" 
("foreach" body line 2) 
invoked from within 
"foreach el $list { 
set sum [expr {$sum+$element }] 
}n 


Tcl provides one other piece of information about error conditions in the 
global variable errorcode. errorcode has a format that 1s easy to process with 
Tcl scripts; it is most commonly used in Tcl scripts that attempt to recover 
from errors using the catch command, described later. The errorcoae variable 
consists of a list with one or more elements. The first element identifies a 
general class of errors, and the remaining elements provide more 
information in a class-dependent fashion. For example, if the first element of 
errorCode 1S postx, 1t means that an error occurred in a POSIX system call. 
errorcode then contains two additional elements giving the POSIX name for 
the error, such as enoznr, and a human-readable message describing the error. 
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Other error codes indicate arithmetic, file access, and child process 
exceptions. Not all Tcl commands set the error code explicitly. If a 
command generates an error without setting errorcode, Tel fills it in with the 
value none. See the reference documentation for a complete description of all 
the forms errorcode can take. 


13.3 Generating Errors from Tel Scripts 


Tcl errors may be generated by the C code that implements the Tcl 
interpreter and built-in commands, or by scripts using the Tcl error command 
as in the following example: 


ce CeSe = Oy. ||] ie & Toe} fT 
error "x is out of range ($x)" 
} 


The error command generates an error and uses its argument as the error 
message. 

As a matter of programming style, you should use the error command only in 
situations where the correct action is to abort the script being executed. If 
you think that an error is likely to be recovered from without aborting the 
entire script, it is probably better to use the normal return value mechanism 
to indicate success or failure (e.g., return one value from a command if it 
succeeded and another if it failed, or set variables to indicate success or 
failure). Although it is possible to recover from errors (you'll see how in 
Section 13.4), the recovery mechanism is more complicated than the normal 
return value mechanism. Thus, you should generate errors only when 
recovery is unlikely. 


13.4 Trapping Errors with cate 


Errors generally cause all active Tcl commands to abort execution, but there 
are some situations where it is useful to continue executing a script after an 
error has occurred. For example, suppose that you want to use the open 
command to open a file to read its contents. (Tcl commands for manipulating 
files are discussed in Chapter 11.) Although Tcl provides the fite readable 
command to test whether a file exists and your process has permission to 
read its contents, another process on your system could delete the file before 
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you get the opportunity to open it. If the file does not exist, open generates an 
error: 


open msg.txt 
@ couldn't open “msg.txt": no such file or directory 


You can use the catch command to ignore the error in this situation: 


catch {open msg. txt} 
=> 1 


The argument to catch 18 a Tel script, which catcn evaluates. If the script 
completes normally, catch returns o. If an error occurs in the script, catch 
traps the error (so that the catcn command itself is not aborted by the error) 
and returns i to indicate that an error occurred. This example ignores any 
errors 1N open. However, we would still need to test the return value of catch 
to determine if the open was successful or not. 

The catch command can also take a second argument. If the argument is 
provided, it 1s the name of a variable, and catch modifies the variable to 
hold either the script’s return value (if it returns normally) or the error 
message (if the script generates an error): 


catch {open msg.txt} fid 
= 2 
set fid 
=> couldn't open "msg.txt": no such file or directory 


In this case, the open command generates an error, SO fia 1S set to contain the 
error message. If the file had existed, open would have returned successfully, 
so the return value from catch would have been o and sia would have 
contained the return value from the open command, which is the channel 
identifier of the file opened. This longer form of catcn is useful 1f you need 
access to the return value when the script completes successfully. It’s also 
useful if you need to do something with the error message after an error, 
such as logging it to a file. 

You can also provide a variable name as an optional third argument to 
capture the return options dictionary, which is described in the next section. 


13.5 Exceptions in General 


Errors are not the only things in Tcl that cause work in progress to be 
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aborted. Errors are just one example of a set of events called exceptions. In 
addition to errors, there are three other kinds of exceptions in Tcl, which are 
generated by the break, continue, and return commands. All exceptions cause 
active scripts to be aborted in the same way, except for two differences. 
First, the errormnfo and errorcode variables are set only during error 
exceptions. Second, the exceptions other than errors are almost always 
caught by an enclosing command, whereas errors usually unwind all the 
work in progress. For example, the break and continue commands are 
normally invoked inside a looping command such as foreach} foreach catches 
preak and continue exceptions and terminates the loop or skips to the next 
iteration. Similarly, return is normally invoked only inside a procedure or a 
file being sourced. Both the procedure implementation and the source 
command catch return exceptions. 


Note 


If a break OF continue Command is invoked outside any loop, active 
scripts are unwound until the outermost script for a procedure is 
reached or all scripts in progress have been unwound. At this point Tcl 
turns the break OF continue exception into an error with an appropriate 
message. 


All exceptions are accompanied by a string value. In the case of an error, 
the string is the error message. In the case of return, the string is the return 
value for the procedure or script. In the case of break and continue, the string 
is always empty. 

The catch command actually catches all exceptions, not just errors. The 
return value from catch indicates what kind of exception occurred, and the 
variable specified in catcn’s second argument is set to hold the string 
associated with the exception. 

Table 13.1 describes the standard exception types. The first column 
indicates the value returned by catcn in each instance. The second column 
describes when the exception occurs and the meaning of the string 
associated with the exception. The last column lists the commands that catch 
exceptions of that type (“procedures” means that the exception is caught by a 
Tcl procedure when its entire body has been aborted). The top row refers to 
normal returns where there is no exception. 


Table 13.1 Summary of Tcl Exceptions 
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Return value 


from catch Description Caught by 

0 Normal return. String gives areturn value. —_ Not applicable 

1 Error. String gives a message describing catch 
the problem. 

2 The return command was invoked. catch, source, 
String gives a return value for the proce- procedures 


dure or source command. 


3 The break command was invoked. String catch, for, foreach, 
is empty. while, procedures 

4 The continue command was invoked. catch, for, foreach, 
String is empty. while, procedures 

anything else Defined by the user or application catch 


In the following example, the catcn command has a return value of 2, which 
indicates that it encountered a return condition while executing its script 
argument. catch Stores the string associated with the exception in the variable 


string. 


catch {return "all done"} string 
=> 2 

set string 
=> all done 


Whereas catch provides a general mechanism for catching exceptions of all 
types, return provides a general mechanism for generating exceptions of all 
types. If its first argument consists of the keyword -code, as 1n 


return -code return 42 


its second argument is the name of an exception (return in this case), and the 
third argument is the string associated with the exception. The enclosing 
procedure returns immediately, but instead of a normal return it returns with 
the exception described by the return command’s arguments. In the preceding 
example, the procedure generates a return exception, which then causes the 
calling procedure to return as well. 

Additionally, the return command allows any number of option-value pairs, 
where you can select any name desired for the options. Some option names, 
which are listed in Table 13.2, receive special treatment. All option-value 
pairs become entries in the return options dictionary, which the catch 
command can capture by specifying a variable name as an optional third 
argument. This allows you to pass any arbitrary information desired when 
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raising an exception. Typically this feature is used only when implementing 
advanced control structures. 


Table 13.2 Significant Option Names for the return Command 


return optionname _— Description 


-code code The exception code, as discussed in Table 13.1. 

-errorcode list If the exception code is error, Tcl sets the value of the 
errorCode variable to list if this option is present, NONE 
otherwise. 

-errorinfo info If the exception code is error, Tcl sets the initial value of 


the errorInfo variable to info if this option is present, a 
generated stack trace otherwise. 


-level level The level value must be a non-negative integer. It speci- 
fies a command currently executing level levels up the 
stack, whose return code will be set to the value given by 
-code. The default is 1. 


-options options The value options must be a valid dictionary. The entries 
of that dictionary are treated as additional option-value 
pairs for the return options dictionary. 


In Section 9.6 you saw how a new looping command, a, could be 
implemented as a Tcl procedure using upvar and upiever. However, the 
example in Section 9.6 did not properly handle exceptions within the loop 
body. Here is a new implementation of ao that uses catch and return to deal 
with exceptions properly: 


proc do {varName first last body} { 
upvar 1 $varName v 
for {set v $first} {$v <= $last} {incr v} { 
set code [catch {uplevel 1 $body} string options] 


switch -- $code { 
0 - 
4 {} 
3 {return} 
default { 


dict incr options -level 
return -options Soptions $string 


} 


This new implementation handles exceptions in much the same way as built- 
in looping commands such as foreach and wniie. It evaluates the loop body 
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inside a catch command and then checks to see how the body terminates. If 
no exception occurs (code 1S 0) or if the exception is a continue (code 1S 4), do 
goes on to the next iteration. If a break exception occurs (code 1S 3), do returns 
to its caller normally, ending the loop. If an error, return, or any other 
completion code occurs, co simply reflects that exception back to its caller. 
When «co reflects an exception to its caller, for the most part all it needs to do 
is pass the entire return options dictionary to its caller. The only change it 
needs to make in the return options dictionary is to increment the value of 
the -1eve1 option by 1. In typical execution, this causes the exception to 
appear in the context of caller, rather than in the context of the ao procedure. 
But it also handles situations properly where the exception had its -1eve1 set 
explicitly in the body of code executed. 


13.6 Background Errors and »sgerror 


A background error is one that occurs in an event handler. For example, if 
an error occurs while executing a command specified with the aster 
command or the -commana option of a widget, it is a background error. For a 
non-background error, the error simply can be returned up through nested 
Tcl command evaluations until it reaches the top-level code in the 
application or is caught and handled with a catch command, as described in 
previous sections. On the other hand, when a background error occurs, the 
unwinding ends in the Tcl library and there is no obvious way for Tel to 
report the error. 

When a Tcl interpreter detects a background error, it saves information 
about the error and invokes a handler command. You can register a 
background error handler with the interp »gerror command; each interpreter 
in your application can have its own background error handler. If you don’t 
explicitly register a background error handler, Tcl uses a default handler. 
For compatibility with versions of Tcl prior to 8.5, the default handler 
checks to see whether a command called ngerror is defined in the interpreter. 
If so, it invokes vgerror and passes a single argument consisting of the error 
message generated; the global errorcode and errorinfo variables are also set to 
their values at the time the error occurred. If you have not registered a 
pgerror COMmand, or an error occurs during the execution of gerror, Tel 
reports the error itself by writing a message to the stderr channel. 

Starting with Tcl 8.5, you can use interp pgerror to register more advanced 
background error handlers. The first argument to interp bgerror 18 a path to 
the interpreter, as defined in Chapter 15; the path ;; refers to the current 
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interpreter. Following that, you can provide additional arguments specifying 
a command and any explicit arguments that you want to pass to that 
command when invoked as the background error handler. When the 
command is invoked, two additional arguments are provided, consisting of 
the error message and a return options dictionary for the error, as discussed 
in Section 13.5. The result is executed in the interpreter’s global 
namespace. Executing interp pgerror With no arguments following the 
interpreter path returns the command prefix currently registered as the 
background error handler. 

The following demonstrates an example of registering a background error 
handler that simply sends the error message and return options dictionary to 
the standard error channel: 


proc myHandler {errMsg returnOpts} { 
puts stderr "Background error: $errMsg" 
puts stderr "Return options dictionary:" 
dict for {key value} $returnOpts { 
puts stderr " $key: $value" 
} 


} 


interp bgerror {} myHandler 
after 0 { expr 1/0 } 
update 
=> Background error: divide by zero 
Return options dictionary: 
-code: 1 
-level: 0 
-errorcode: ARITH DIVZERO {divide by zero} 
-errorinfo: divide by zero 
invoked from within 
"expr 1/0 
("“after”" script) 
-errorline: 1 
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14. Creating and Using Tel Script 
Libraries 


Like any other modern programming language, Tcl allows you to group 
commonly used procedure definitions into Jibraries that can be used by 
many applications. A Tcl library can be as simple as a single script file 
defining a few utility procedures. Or you can combine multiple library 
script files into a single package that you can distribute. Packages also have 
version numbers associated with them, so applications can distinguish 
among different historic versions of a package and require specific ones. 
Additionally, Tcl allows you to bundle entire Tcl applications or libraries 
into single-file packs called Starkits. Combined with the 7c/kit single-file 
Tcl interpreter, this gives you a handy means of distributing your Tcl 
applications. You can even create a single-file application executable called 
a Starpack, which combines a Tclkit for a particular platform with a Starkit 
of your software. 

Modern extensions should be implemented as modules or packages and 
make use of autoloading, where the Tcl interpreter automatically loads 
modules or packages as needed. To support autoloading, the Tcl interpreter 
makes use of a few simple conventions, which grew out of the libraries that 
shipped with early versions of Tcl. 

The following sections show how modern packages and modules are built 
on top of Tcl’s support for libraries of procedures, automatically loading 
scripts as needed. The final section shows how you can use Tclkit and 
Starkits or Starpacks to distribute your applications easily on multiple target 
platforms. 


14.1 Commands Presented in This Chapter 


® auto mkindex dir ?pattern ...? 


Generates an index suitable for use by Tcl’s autoloading mechanism. The 
command searches air for all files whose names match any of the pattern 
arguments (matching is done with the gic» command), generates an index of 
all the Tcl command procedures defined in all the matching files, and stores 
the index information in a file named tcitndex In air. If NO pattern 1S given, a 
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pattern of +.tc1 is assumed. 

® info library 
Returns the name of the library directory in which standard Tcl scripts are 
stored. This is actually the value of the tci_iibrary global variable and may 
be changed by setting tci_iiprary. 

® info loaded ?interp? 
Returns a list describing all of the packages that have been loaded into interp 
with the icaa command. Each list element is a sublist with two elements, 
consisting of the name of the file from which the package was loaded and 
the name of the package. For statically loaded packages the file name is an 
empty string. If interp is omitted, information is returned for all packages 
loaded in any interpreter in the process. To get a list of just the packages in 
the current interpreter, specify an empty string for the interp argument. 

° info sharedlibextension 
Returns the file extension used on this platform for shared libraries. 

® package ifneeded package version script 
Used in a pxgindex.tc1 file to indicate that the specified version Of a package 1S 
available if needed. The optional script argument executed automatically by 
Tel in the package 18 later requested with a package require command. 

® package names 
Returns a list of the names of all packages in the interpreter for which a 
version has been provided (via package provide) OF for Which a package ifneedea 
script is available. 

© package prefer ?latest|stable? 
Sets which type of package is preferred: 1atest, which matches the latest 
version of a package present even if it is an alpha or beta release; or stabie, 
which matches an alpha or beta version of a package only if no stable 
version fulfills the requirements. Once an interpreter’s preference is set to 
latest, attempts to set it back to stapie are ignored. Without an argument, 
package prefer returns the current preference. 


® package provide package ?version? 
Indicates that version version Of package package 18 Now present in the 
interpreter. It is typically invoked once as part of a package ifneedea Script and 
again by the package itself when it 1s finally loaded. If the version argument 
is omitted, the command returns the version number that is currently 
provided, or an empty string if no package proviae command has been invoked 
for package in this interpreter. 

© package require package ?requirement? 

package require -exact package requirement 


Loads the package specified, ensuring that the version requirement 18 met. The 


305 


first version loads the latest version of package available on the system, as 
long as it meets the minimum version requirement and its major version 
number is the same as requirement. With the -exact option, only the version of 
package Specified by requirement 18 accepted. The command returns the version 
Of package loaded, or an error if a package Meeting requirement 18 not available. 

® package vcompare versionl version2 
Compares the two version numbers given by version1 and version2. Returns -1 
if version1 1§ an earlier version than version2, 0 1f they are equal, and : if 
version1 1S later than version2. 

® package versions package 
Returns a list of all the version numbers of package for which information has 
been provided by package ifneedea Commands. 

® pkg mkIndex ?options? dir ?pattern ...? 
Generates a pkgindex.tc1 Index suitable for use by Tcl’s package mechanism. 
The command searches air for all files whose names match any of the pattern 
arguments (matching is done with the gio» command), generates an index of 
all the Tcl command procedures defined in all the matching files, and stores 
the index information in a file named pxgtndex.tc1 IN air. If NO pattern 1S given, 
the default patterns of *.tc1 and *. [info sharedlibextension] are used. See the 
reference documentation and Section 14.5.2 for more information on the 
supported options. 

® s:tcl::tm::path list 
Returns a list containing all registered Tcl module paths, in the order in 
which they are searched for modules. 


14.2 The 1.22 Command 


The ioaa command allows you to load precompiled libraries, typically 
written in C or C+-4, into the Tcl interpreter. To do so, your binary file must 
be created as a shared library on Unix or a Dynamic Link Library (DLL) on 
Windows. Because different platforms use different extensions to identify 
shared library files, Tcl provides the info sharedlibextension Command, which 
returns the shared library extension used by the current system. Thus, a 
shared library is often loaded like this: 


load myextension[info sharedlibextension] 


Your C or C++ code must also follow certain Tcl conventions. Once the 
shared library implementing the package is loaded, the Tcl interpreter calls 
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the initialization function for the package. The name of this function is 
based on the name of the package. For example, with a package named stari, 
the initialization method would be stari_tnit. If the binary file is loaded by a 
safe Tcl interpreter, the initialization function name would be stari_safetnit. 
See Chapter 36 for more information on writing packages in C. 

Once you load a binary file, you can use the into 1oadea command to list all 
packages loaded with the 10aa command. 


14.3 Using Libraries 


A Tcl library is a directory containing one or more Tcl script files 
implementing a related set of procedures. Tcl ships with a standard library 
of procedures that implement some of its default behavior. Understanding 
how the Tcl library works is a good way to learn how to add your own 
libraries and packages. 

The command info tiprary returns the full path name of the Tcl library 
directory, such as 


info library 
= C:/Program Files/Tcl8.5/lib/tcl8.5 


In addition, the global variable +ci_1ibrary holds the same value: 


puts $tcl_library 
= C:/Program Files/Tcl8. 5/lib/tcl8.5 


This directory is used to hold standard scripts used by Tel, such as a default 
definition for the unknown procedure described next. 


14.4 Autoloading 


Section 15.10 describes how Tcl handles processing unknown commands by 
invoking a procedure called unknown. Tcl has a default implementation of the 
unknown Command, but you can define your own to implement custom 
functionality. One of the most useful functions performed by the default 
unknown procedure is autoloading. Autoloading allows you to write 
collections of Tcl procedures and place them in script files in library 
directories. You can then use these procedures in your Tcl applications 
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without having to source the files that define them explicitly; you simply 
invoke the procedures. The first time that you invoke a library procedure it 
doesn’t exist, SO unknown 18 Called. unknown finds the file that defines the 
procedure, sources the file to define the procedure, and then re-invokes the 
original command. The next time the procedure is invoked it exists, so the 
autoloading mechanism isn’t triggered. 

Autoloading provides two benefits. First, it makes it easy to build large 
libraries of useful procedures and use them in Tcl scripts. You need not 
know exactly which files to source to define which procedures, since the 
autoloader takes care of that for you. The second benefit of autoloading is 
efficiency. Without autoloading, an application must source all of its script 
files when it starts. Autoloading allows an application to start up without 
loading any script files at all; the files are loaded later when their 
procedures are needed, and some files may never be loaded at all. Thus 
autoloading reduces startup time and saves memory. 

The autoloader is straightforward to use. First, create a library as a set of 
script files in a single directory. Normally these files have names that end in 
tcl, for example, ab.tc1 OF stretch.tc1. Each file can contain any number of 
procedure definitions. It’s a good practice to keep the files relatively small, 
with just a few related procedures in each one. In order for the autoloader to 
handle the files properly, the proc command for each procedure definition 
must be at the beginning of a line with no leading space, and it must be 
followed immediately by whitespace and the procedure’s name on the same 
line. Other than this, the format of the script files doesn’t matter as long as 
they are valid Tcl scripts. 

The second step in using the autoloader is to build an index. To do this, start 
a Tcl application such as tcisn and invoke the auto mkindex command as in the 
following example: 


auto_mkindex . *.tcl 


auto_mkindex 1$n’t a built-in command but rather a procedure in Tcl’s script 
library. Its first argument is a directory name, and the second argument is a 
glob-style pattern that selects one or more script files in the directory. 
auto_mkindex Scans all of the files whose names match the pattern and builds 
an index that indicates which procedures are defined in which files. It stores 
the index in a file called tcitnaex in the directory. If you modify the files to 
add or delete procedures, you should regenerate the index. 

The final step is to set the variable auto patn in the applications that wish to 
use the library. The auto path variable contains a list of directory names. 
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When the autoloader is invoked, it searches the directories in auto path In 
order, looking in their tcitnaex files for the desired procedure. If the same 
procedure is defined in several libraries, the autoloader uses the one from 
the earliest directory in auto path. Typically, auto path 18 set as part of an 
application’s startup script. For example, if an application uses a library in 
the directory /usr/iocai/1ib/shapes, It might include the following command in 
its startup script: 


set auto path \ 
{linsert Sauto_path 0 /usr/local/1ib/shapes] 


This adds /usr/iocai/1ib/shapes to the beginning of the path, retaining all the 
existing directories in the path such as those for the Tcl and Tk script 
libraries but giving higher priority to procedures defined in 
/usr/local/lib/shapes. Once a directory has been properly indexed and added 
tO auto_patn, all of its procedures become available through autoloading. 


Note 


More complex libraries—especially those involving an integrated 
mixture of Tcl scripts and C extensions, or where there is a need to 
maintain multiple versions of a library—are better implemented as 
packages. Packages are also strongly preferred when libraries are 
distributed to other people, since they are considerably easier to 
manage and install. 


14.5 Packages 


Creating libraries gives you the ability to collect useful utility procedures 
and build libraries of code for reuse. With autoloading, your Tcl programs 
gain efficiencies by loading only what is needed. Even so, Tel libraries 
don’t provide a number of useful features such as versioning and better code 
separation. For example, if you have two procedures with the same name, 
the first one found in the library path, auto patn, gets called. 


Note 
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You can alleviate some of this problem by using namespaces, covered 
in Chapter 10. 


By creating a Tcl package, you can add versioning and provide a better 
organization to your library code. 


14.5.1 Using Packages 


Tcl already comes with a number of packages, but you can also download 
many more. (Appendix B describes some of the popular Tcl packages 
available that extend Tcl’s functionality.) To use a package, specify the 
package name and version with the package require command; for example: 


package require platform 1.0.3 


This command attempts to load the required package. Once it is loaded, you 
can call on the functionality of the package within your Tcl program. 

By convention, versions with the same major number are considered 
compatible; that is, if your code asks for piatform at version 1.0, then 1.0.3, 
1.1, 1.2, or other higher minor versions would satisfy the requirement. In 
this case, a package at version 1.0.4 would satisfy the requirement, but 1.0.2 
would not. In addition, a version of 2.0 would not satisfy the requirement. 
The Tcl package mechanism selects the highest-numbered compatible 
version of the package that satisfies the requirement. 

If you are not concerned with the version number, use a command like the 
following: 


package require platform 


This command loads the highest version of the package installed on your 
system. Or, if you require an exact version, use the -exact option: 


package require -exact platform 1.0.3 


Note 


Version numbers can also include an a for alpha or a 5 for beta, such as 
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1.3b1. These letters indicate unstable packages. Package versions 
without letters indicate stable versions. Tcl normally prefers stable 
over unstable versions. You can change the preference to load the latest 
available version of a package, even if it is alpha or beta, with the 
command 


package prefer latest 


14.5.2 Creating Packages 


A Tcl package 1s a directory of one or more Tcl scripts and/or binary shared 
libraries. Each Tcl script in the package should declare that it provides the 
package with the package provide Command; for example: 


package provide platform 1.0.3 


This command specifies that the source in the file provides (or helps to 
provide if there is more than one Tel script in the directory) a package 
named piatform. The version number is 1.0.3. with the major number of | and 
a minor number of 0.3. Missing numbers are treated as zeros, so 1.0.3 is the 
same as 1.0.3.0 and 1.0.3.0.0.0. You can make a long version number if 
needed, such as 1.0.3.0.3.0.3.0.3.0.3, though this is not necessary in most 
cases. You might also use a build number or a timestamp as part of the 
version number, such as 1.1.20080829. 


Note 


The first number, the major number, is the most important. You should 
increment your package’s major version number whenever you make a 
change that is not backward-compatible with previous versions. 


When you create a package, place all your code into a single directory. Then 
you need to create a pxgindex.tci file, which the Tcl interpreter uses to load 
your package. You can create this file by hand, and if you have a complex 
case you'll need to do so. But most packages can use the handy pxg_mktnaex 
procedure. pxg mkindex creates the index file needed by the Tcl package 
system to manage loading your package. As with auto _mkindex, pkg_mkIndex 1$n’t 
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a built-in command but rather a procedure in Tcl’s script library. 


Note 


Even if you write your OWN pxgindex.tc1 script, you can use the 
pkg_mkIndex procedure as a guide that defines what the Tcl interpreter 
expects 1N a pkgindex.tcl Script. 


The basic format of the command is 
pkg_mkIndex . *.tcl 


This command looks at all files with names ending in .¢ci in the current 
directory and creates the package index in the file pxgtndex.tci1 in the 
directory indexed. The pxgindex.tc1 holds one or more package ifneeded 
commands, along with the scripts needed to load the packages; for example: 


package ifneeded app-starl1 1.0 \ 
(list source [file join $dir starl.tcl]] 


This command specifies a package named app-stari at version i.0. The 
command to load the package is to source in the Tel script file, star1.tci. The 
value sair gets passed in by the Tcl interpreter when loading the package. 
The first time a package require command gets executed, the Tcl interpreter 
executes the package unknown Script. This script sources all the pkgindex.tci files 
found in the directories listed in the auto patn global variable and their 
immediate subdirectories. 


Note 


Any platform-specific binary files must be set up to be loaded with the 
loaa Command, described in Section 14.2. In addition, the binary file 
must contain a call to the C function rc1_pxgprovide. 


pkg_mkIndex Supports a number of options, including -cirect, to specify loading 
the package files when a package require command is executed, which is the 
default. The -1azy option is discouraged, but it sets up the package to get 
loaded only when one of the procedures in the package 1s first called. The - 
verbose Option tells pkg mktnaex to Output status information as it works. A 
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special option, -10aa, specifies which packages to preload using a pattern. 
This is to help index packages containing binary files that in turn depend on 
other packages. 


14.5.3 Using :ipkg: :create 


The ::pxg::create procedure creates the package ifneedea Command used in the 
pkgindex.tcl files. You can also use ::pkg::create When creating your 
pkgIndex.tcl files by hand. Normally you can simply use px¢_mxtndex to create a 
package index script. The basic syntax 1s 


::pkg::create -name package_name \ 
-version version_number -source tcl_scripts 


The -source parameter takes a list with the first element being a file name and 
the second an optional list of commands provided in the file; for example: 


::pkg::create -name foo -version 99.5 -source starl.tcl 
=> package ifneeded foo 99.5 [list source [file join $dir star.tcl]] 


If you have a binary file, use the -10aa option: 
::pkg::create -name package_name \ 


-version version_number \ 
-load {binary file commands provided} 


The -icaa parameter takes a list whose first element is a file name and the 
second is an optional list of commands provided in the binary file. 


14.5.4 Installing Packages 


To install your new package, install the package’s directory as a 
subdirectory of any directory listed in the ::tci_pxgpatn variable. Once your 
package is installed, the package require command can find it. 


Note 


By convention, if the ::tci_pxgpatn variable contains more than one 
directory, you should place platform-specific packages into the first 
directory in the list. Place platform-agnostic packages in the second 
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directory in the list. 


If you need to install your package in another location (that is, not under the 
directories listed in the ::tci pxgpatnh variable)—or if the ::tci_pkgpath 
variable is not set on your system—you must place your directory under one 
of the directories listed in the ::auto patn variable. Typically, the directory in 
which Tcl looks for its initialization scripts is one of the directories listed in 
the ::auto path variable; the info 1ibrary command returns the name of this 
directory. When in doubt, this directory is often a reasonable target 
directory for installing your package. 

You can also add the directory name where you installed your package to 
the ::auto path variable. You need to do this only if you install your package 
to a nonstandard location. 


14.5.5 Utility Package Commands 


The package names Command lists all packages installed: 
package names 


= activestate::teapot::link http platform tcl::tommath tcltest 
msgcat ActiveTcl Tcl 


Note 


This example shows packages installed with ActiveTcl. 


The package versions Command returns a list of all versions of a package that 
are available on the system: 


package versions mypackage 
= 1.01.1 


When the package provide Command is executed without a version number, it 
returns the version number that is currently provided, or an empty string if 
NO package provide Command has been invoked for the package in this 
interpreter: 


package provide Trf 
=> 2.1.2 
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14.6 Tcl Modules 


The historical mechanism for locating and loading packages employed by 
the Tcl core is very flexible, but it suffers from drawbacks as well. The 
primary problems with the historical mechanism are that it extensively 
searches the file system for packages, and that it has to actually read a file 
(pxgindex.tc1) to get the full information for a prospective package. All of 
these operations take time. The fact that “index scripts” are able to extend 
the list of paths searched tends to heighten this cost, as it forces rescans of 
the file system. Installations where directories in the auto path are large or 
mounted from remote hosts are hit especially hard by this (especially 
network delays). All of this together causes a slow startup of tcisn and Tcl- 
based applications, especially for systems with an extensive collection of 
packages located on remote hosts. 

Tcl 8.5 added support for Zc! modules, which are less flexible than 
traditional packages but require far less file system access by the Tcl 
interpreter when it is searching for available packages and modules. Tcl 
modules are the recommended method for creating and distributing 
extensions in Tcl 8.5 and beyond. 

The main simplification is that each module must be stored in a single file, a 
file that is read with the Tcl source command. Inside the file, the module may 
define one or more Tcl packages, as described in Section 14.5. Typically, 
each module file defines a single Tcl package. You can store binary data 
within the same file after a controi-z, which ends the reading of Tel 
commands. The other simplification is that there is no index file for the 
module (that is, you don’t create a tcitndex OF pkgindex.tci file to accompany 
the module). The name of the module file and its location are enough to tell 
the Tcl interpreter what package and version the module provides. 


Note 


For more information on creating modules containing binary data, 
embedded ZIP archives, and other more complex structures, see the 
documentation for TIP 190 at nttp://tip.tci.tk/is9.ntm and search for 
related articles on the Tcler’s Wiki at neto://wiki.tcl.tk/. 
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14.6.1 Using Tcl Modules 


To use packages defined in Tcl modules, place a package require Command 
within your Tcl program, just as for any package; for example: 


package require platform::shell 1.1.3 


The Tcl interpreter looks first for packages within Tcl module files. Tcl 
searches a list of directories known as the module path, which is 
completely independent of the auto patn list of directories described in 
Section 14.5.4. Only if an appropriate Tcl module is not found does Tcl fall 
back to using the traditional method of scanning the directories listed in 
auto path for a package meeting the requirements. 


14.6.2 Installing Tcl Modules 


When creating modules, you must store them in a file whose name matches 
the regular expression 


([[:alpha:]][:[:alnum:]]*)-([[:digit:]].*)\.tm 


The first part of the file name specifies the name of the package, such as 
myutils. The portion of the file name following the - is the version number. 
Module file names must end in a .tm extension. For example, the following 
are valid module file names: 


tcltest-2.3.0.tm 
http-2.7.tm 
shell-1.1.3.tm 
myutils-1.1.20080829.tm 


The directory tree for storing Tcl modules is independent of auto patn. Tel 
modules are searched for in all directories listed in the result of the 
command ::tci::tm::path list. This is called the module path. Neither the 
auto path Nor the tc1 pkgpatn variable is used. 

When an application requests a package, before the search is started, the 
name of the requested package 1s translated into a partial path, where all 
occurrences of :: in the package name are replaced by the appropriate 
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directory separator character for the platform. Thus on Unix each :: in the 
requested package name is translated to a /. For example, 


package require encoding::base64 


results in a partial path of encoding/baseos. After this translation, Tcl joins this 
partial path to the end of each directory in Tcl’s module path list—which 
consists of a set of directories where Tcl looks for modules—to form a set 
of search patterns. The patterns are tested in the order of the module paths to 
search for a matching module file. 
The default module path list is computed by tcish based on the major and 
minor versions of the Tcl interpreter. So, using x to indicate the major 
version and y to indicate each minor version less than or equal to the current 
minor version, the default path list consists of the following: 

® file normalize [info library]/../tclX/X. Y 

file normalize [info nameofexecutable]/../lib/tclX/ xX. Y 

Thus, a version 8.5 Tcl interpreter would include a set of directories 
tcl8/8.5, tcl8/8.4, tcl8/8.3, tcl8/8.2, tcl8/8.1, aNd tcis/s.o, Where the tcis 
directory is at the same level as the Tcl library directory returned by into 
library. 

® file normalize [info library]/../tclX/site-tcl 
Note that this is always a single entry, because x is the specific current 
major Tcl version. 

® S::env(TCLX_Y TM PATH) 
A list of paths, separated by either : on Unix or ; on Windows. Note that x 
and y follow the general rules mentioned above, so for Tcl 8.5, this would 
mean that six different environment variables would be looked for: 
TCL8_5 TM PATH through TCL8_0 TM PATH. 
The command ::tci::tm::path list returns the current module path list. You 
can add directories to the list and remove them by using ::tci::tm::path add 
and ::tcl::tm::path remove. See the tm reference documentation for more 
information. 
As an example, consider the case where you’ve created the first version of a 
package that people would load into their application with the command 


package require struct::btree 


Further assume that you designed the package using features of Tcl 8.4, and 
it does not require any 8.5 features. If this were a module for your own 
personal use, you might put it in a subdirectory of your home directory. 
Assuming that your home directory is /users/xen, the complete path name for 
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the module might be 


/Users/ken/modules/struct/btree-1.0.tm 


You could create an environment variable named rcis 4 ™ pars and include 
the directory /users/ken/modules aS One of its values. 

On the other hand, if your module were for general use by all users of your 
system, and Tcl is installed such that info 1iprary returns c:\rcis.5\1ib, the 
complete path name for the module might be 


CATcI8.5\lib\tcl8\site-tcl\struct\btree-1.0.tm 


If you plan to distribute the module, you could create a simple installation 
script that would query the info 1ibrary command, and then install your 
module as 


file normalize [info library]/../tcl8/8.4/struct/btree-1.0.tm 


14.7 Packaging Your Scripts as Starkits 


A Starkit provides a single-file distribution of your Tcl procedures, 
application data, and, if needed, platform-specific compiled code. This 
allows you to bundle an entire Tcl application as a single file. 


Note 


The name comes from an abbreviation for “stand-alone runtime.” 


The Starkit itself uses Tcl’s virtual file system support to present your 
application with a common directory structure for locating code, application 
data, and other files. The files within the Starkit appear to your application 
as normal files, shielding your application from the bundling format. 

To run the application within a Starkit, you need to use a special Tcl 
interpreter, called a Tclkit. A Tclkit is a platform-specific Tcl interpreter, 
built with a known set of Tcl extensions—extensions needed to extract and 
run your application from the virtual file system used by the Starkit. While a 
normal Tcl installation consists of hundreds of files, with a Tclkit you get a 
single-file executable with the entire Tcl distribution. 
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Note 


As a Single-file distribution mechanism, a Starkit is similar to a Java 
Jar file, and Tclkit is similar to the Java Runtime Engine, or JRE. The 
main difference is that you execute your Starkit directly using the Tclkit 
interpreter for a particular platform. 


The Tclkit/Starkit combination mostly provides convenience for bundling 
and distribution—convenience for the end users of your Tcl programs. 
Without a facility like Tclkit and Starkits, you need several items to be able 
to deploy a Tcl program: 

¢ A Tcl interpreter 

¢ Platform-specific compiled libraries 

* Tcl scripts that make up the Tcl standard library 

¢ Any Tcl extensions needed by your application 

¢ Any Tcl library code not part of the standard distribution but needed 

by your application 

¢ Your application scripts 

¢ Any platform-specific compiled code needed by your application 

¢ Any data files needed by your application 
The Starkit system divides these items into two bundles. The Tclkit provides 
the Tcl interpreter and a set of Tcl extensions, including everything 
necessary to run Starkit applications. The Starkit, which you create, contains 
your application scripts, any platform-specific compiled code needed, and 
your application data. 
The next sections show how to create and work with Starkits. To create a 
Starkit, you first need to install a Tclkit interpreter. 


14.7.1 Installing a Telkit 


Download a_ Tclkit interpreter for your' platform from 


http://www.equi4.com/tclkit/download.html. Each Telkit interpreter includes Tel, 
Tk, IncrTcl, Metakit (a small embedded database library), and TclVFS 
support for virtual file systems. 


Note 
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Find out more about Telkits at nity: //www.equid.com/tclkit/. 


Normally, you just need to uncompress the downloaded file and you have a 
complete Tcl interpreter. You can invoke the Tclkit interpreter just as you 
would a tcisn and use it to run normal Tcl script applications as well as 
Starkit applications. Running a Starkit with a Tclkit is much like running a 
standard Tcl script: 


tclkit starkitfile ?arguments_to_starkit ...? 


14.7.2 Creating Starkits 


The next step to creating Starkits 1s to download the sax Starkit. sax is a 
Starkit designed to help you create your own Starkits, allowing you to wrap 
your application as a Starkit, unwrap a Starkit, or show information on the 
contents of a Starkit. Download sax from netp: //www.equid.com/pub/sk/sdx.kit and 
find out more information at netp: //wiki.tcl.tk/sax. 


Note 


Keep the sax.xit available when working with Starkits. 


To get started quickly, you can use the sax qvrap command to create a Starkit 
from a single Tcl script. For example, create a Tcl script like the following 
and name the file stari.tc1: 


puts "Hello from a Starkit." 


Then run the following command to create a Starkit from this short Tcl 
script: 


tclkit sdx.kit qwrap star1.tcl 


This command creates a small file named stari.xit. Run the new Starkit with 
a command like the following: 


tclkit star1.kit 
=> Hello from a Starkit. 
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Run the sax 1sk command to view the directory structure within the Starkit 
file: 


telkit sdx.kit lsk starl.kit 
starl.kit: 
dir lib/ 
75 2008/06/19 19:25:21 main.tcl 


starl.kit/lib: 
dir app-starl/ 


starl.kit/lib/app-starl: 
76 2008/06/19 19:25:21 pkgIndex.tcl 
2 2008/06/19 19:25:21 starl.tcl 


VUUUEUNNUNY 


You can extract these files with the sax unwrap command: 


tclkit sdx.kit unwrap star1.kit 
=> 5 updates applied 


This command creates a local file copy of the virtual file system in the 
Starkit file stored under the stari1.ves directory. Inside this directory, you see 
a file structure like the following: 


main.tcl 

lib/ 

lib/app-starl1/ 
lib/app-starl1/pkgIndex.tcl 
lib/app-starl/starl.tcl 


All references to the name stari come from the name of the original source 
file, stari.tci. Following Starkit conventions, the package created for your 
application uses the prefix app-. 

To run an expanded Starkit, use a command like the following: 


tcelkit star1.vfs/main.tcl 
=> Hello from a Starkit. 


The main.tci script contains the following code: 


package require starkit 
starkit::startup 
package require app-starl 


The starxit package provides the necessary code to initialize the Starkit 
virtual file system. The starkit::startup procedure adds the internal Starkit iip 
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directory to the Tcl auto patn variable. This makes all packages within the 
Starkit available to your application. You can add packages to the iin 
directory and then access these packages in your scripts normally. The final 
package require COMMand sourceS your program’s script. 

The pxgindex.tc1 script defines the package index: 


package ifneeded app-starl 1.0 \ 
[list source [file join $dir starl.tcl]] 


And the sax qvrap command modifies your original Tcl script to include a 
package provide command: 


package provide app-star1 1.0 
puts "Hello from a Starkit." 


Creating Starkits from an application consisting of multiple Tcl scripts and 
other extensions, encodings, image files, data files, and other auxiliary files 
is not much more difficult. You need to first create a directory structure 
similar to what the sax unwrap Command creates when unwrapping a Starkit. 
The top-level directory name is your application name followed by .ves. 
Within it should be a file called main.tci, which is executed automatically 
when the Starkit is run. This file should have the same content as previously 
shown, except the final package require Specifies the name of your application 
“package.” The main script of your application needs to have an appropriate 
package provide Command, and you must also have a minimal pxgtndex.tci file 
that describes how to source the main script. Beyond that, your script can use 
source, package require, and other Tcl commands to load scripts and other 
auxiliary files from your .ves directory structure. Once you have completed 
development of your application, you can use the sax wrap command to wrap 
all of the files within the .vss directory into a Starkit: 


tclkit sdx.kit wrap star1.kit 


Note 


You can also bundle platform-specific C extensions inside your 
Starkits. For more information on including additional files, including 
C-based extensions, read the documentation available at 
http: //www.equi4.com/tclkit/. 
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14.7.3 Creating a Platform-Specific Executable 


With Starkits, you need the separate platform-specific Tclkit interpreter to 
run your application. A Starpack 1s a combination of a platform-specific 
Tclkit interpreter and a Starkit, allowing you to provide your users with a 
single-file application. An advantage of this is that your users no longer 
need to know that you used Tcl to create the application, as the platform- 
specific executable hides the underlying technology from users. 

To create a Starpack, use the sax wrap command with the -runtime option: 


tclkit sdx.kit wrap starl -runtime tclkit-darwin-univ-aqua 
=> 4 updates applied 


In this command, stari names the output executable. Use a name like stari.exe 
on Windows. The -runtime option specifies the Tclkit interpreter to use to 
create the new executable. You cannot create your Starpack using the Tclkit 
interpreter that is running the sax command; of course, you can simply make 
a copy of the Tclkit interpreter. 

When you’re done, you can run your new command; for example: 


/star1 
=> Hello from a Starkit. 


On Unix systems, you can use the fi1e command to verify what you built; for 
example: 


file starl 
=> starl: Mach-O universal binary with 2 architectures 
=> starl (for architecture ppc): Mach-O executable ppc 
=> starl (for architecture i386): Mach-O executable i386 


In this case, for Mac OS X, the built executable runs on both PowerPC and 
Intel platforms under Mac OS X. 

For more on Starkits, see nttp: //www.equi4.com/papers/skpaper1.htm1. You can also 
download other Starkits and use the sax unwrap Command to see what lies 
inside. 
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15. Managing Tcl Internals 


This chapter describes a collection of introspection commands that allow 
you to query and manipulate the internal state of the Tcl interpreter and to 
create helper interpreters for specialized tasks. For example, you can use 
these commands to see if a variable exists, to monitor all uses of a variable 
or command, to rename or delete a command, to handle references to 
undefined commands, or to create an interpreter suited to executing scripts 
dealing with data from untrusted sources. This chapter also discusses Tcl’s 
features for time and date manipulation, measuring how long code execution 
takes, temporarily pausing script execution, and scheduling actions to take 
place after a delay. 


15.1 Commands Presented in This Chapter 


This chapter discusses the following Tcl commands for managing interpreter 
internals: 
* after ms 
Sleeps for ms milliseconds and then returns. 
® after ms ?script script ...? 
Concatenates the script arguments in the same fashion as the concat command, 
and then arranges to execute the resulting script in the global scope after ms 
milliseconds. Returns a unique token identifying the registered script. 


® after cancel id 


Cancels the execution of a delayed script previously registered with after. ia 
is the unique identifier returned by arter when the script was registered. If 
the script has already been executed, the after cancer command has no effect. 
® after idle script ?script ...? 
Concatenates the script arguments in the same fashion as the concat Command, 
and then arranges to execute the resulting script in the global scope as an 
idle callback. The script is run exactly once, the next time the event loop is 
entered and there are no events to process. Returns a unique token 
identifying the registered script. 


® clock seconds 


clock microseconds 
clock milliseconds 


Returns the current time as an integer number of seconds, milliseconds, or 
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microseconds since the epoch (see Section 15.3). 
® clock format timeVal ?-option value ...? 

Accepts a timeval expressed as an integer number of seconds since the 

epoch, and returns a time and date string intended for consumption by users 

or external programs. See the text and the reference documentation for more 


details. 


® clock scan inputString ?-option value ...? 


Accepts a time and date string intended for users or external programs and 
returns a time expressed as an integer number of seconds since the epoch. 
Raises an error if the string cannot be converted. See the text and the 
reference documentation for more details. 

® clock add timeVal ?count unit ...? ?-option value ...? 
Accepts a timevai expressed as an integer number of seconds since the epoch 
and adds (possibly negative) count units of time to the value, returning the 
resulting time as an integer. See the text and the reference documentation for 
more details. 

® info args procName 
Returns a list whose elements are the names of the arguments to the 
procedure called procwame, in order. 


° info body procName 


Returns the body of the procedure called procname. 


® info cmdcount 


Returns a count of the total number of Tcl commands that have been 
executed in this interpreter. 


® info commands ?pattern? 


Returns a list of all the commands that are visible in the current or specified 
namespace, including built-in commands, application-defined commands, 
procedures, ensembles, and aliases. If pattern is specified, only the 
command names matching pattern are returned; matching is determined using 
the same rules as string match. If the pattern includes an absolute or relative 
namespace reference, only the commands from the specified namespace 
matching the pattern are listed. 


® info complete script 


Returns : if script 1s a syntactically complete sequence of one or more Tcl 
commands, o if not. This only determines whether the commands in the 
script have correctly balanced braces, closed quotes, etc.; it does not ensure 
that the commands have the correct argument formats. 


® info default procName argName varName 


Checks to see if the argument argwame to the procedure procname has a default 
value. If so, it stores the default value in the variable varwame and returns 1. 
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Otherwise, it returns o and puts the empty string in varname. 


® info exists varName 


Returns 1 if there exists a variable named varname 1n the current context, o if 
no such variable is currently accessible. 
® info globals ?pattern? 
Returns a list of all the global variables currently defined. If pattern is 
specified, only the global variable names matching pattern are returned, 
USING string match’s rules for matching. 
° info hostname 
Returns the host name of the machine on which the Tcl interpreter is running. 
° info level ?number? 
If number 18 not specified, returns a number giving the current stack level (0 
corresponds to the top-level, i to the first level of procedure call, and so 
on). If number 18 specified, it returns a list whose elements are the name and 
arguments for the procedure call at level numer. 
® info library 
Returns the full path name of the library directory in which standard Tcl 
scripts are stored. 
® info locals ?pattern? 
Returns a list of all the local variables defined for the current procedure, or 
an empty list if no procedure is active. If pattern 1s specified, only the local 
variable names matching pattern are returned, using string matcn’S rules for 
matching. 
® info nameofexecutable 
Returns the full name of the executable containing the Tcl interpreter. 
® info patchlevel 
Returns the current release version of the Tcl interpreter. 
® info procs ?pattern? 
Returns a list of the names of all procedures currently defined in the current 
namespace. If pattern 1s specified, only the procedure names matching pattern 
are returned, using string matcn’s rules for matching, If the pattern includes an 
absolute or relative namespace reference, only the procedures from the 
specified namespace matching the patrern are listed. 
® info script ?filename? 
If riiename 18 not specified, returns the name of the script file currently being 
evaluated or the empty string if no script file is being executed. If ritename 1s 
specified, the value to be returned by into script (without arguments) is set to 
be filename until the enclosing procedure call terminates. 


info sharedlibextension 


Returns the platform’s default file name extension for shared libraries. 
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® info tclversion 


Returns the version number for the Tcl interpreter in the form major.minor. 


® info vars ?pattern? 


Returns a list of the names of all variables that are currently accessible. If 
pattern 18 Specified, only the variable names matching pattern are returned, 
USING string match’S rules for matching. 
* interp alias srcPath srcCmd ?targetPath? ?targetCmd? 
arg arg ...? 

Creates, deletes, and manipulates command aliases between and within 
interpreters. If the targetratn and later arguments are omitted, it returns the 
current definition of the command alias with the name srccma in the 
interpreter srcratn (which may be empty to refer to the current interpreter). If 
targetPath 1S present as the empty string but no further arguments are present, 
the alias called srccma in the interpreter srcpatn 18 deleted. If targetcma and any 
optional extra arguments are present, the alias called srccma in the interpreter 
srckath 18 defined to indicate the command ¢targetcma in the interpreter 
targetpath With the extra arguments all prefixed before any caller-supplied 


arguments. 


® interp create ?-safe? ?--? ?path? 


Creates the interpreter referred to by patn and returns the name of the 
interpreter created. The optional argument -- indicates the end of the 
optional arguments and should be used if patn could start with a hyphen. The 
optional -sare argument results in a safe interpreter with all unsafe core Tcl 
commands hidden. If path 1s omitted, the interp command creates a direct 
child of the current interpreter with an automatically generated name. 

* interp delete path 
Deletes the interpreter referred to by patn and any slave interpreters it has. 

® interp eval path arg ?arg ...? 
Evaluates in the interpreter referred to by patn the script formed by 
concatenating the given arg arguments. 

® interp expose path hiddenName ?cmdName? 
Exposes the hidden command called niadenvame in the interpreter pacn. If 
cmdName 18 present, the command is exposed as that; otherwise it is exposed 


with the name it had when hidden. 


® interp hide path cmdName ?hiddenName? 


Hides the command called cmavame in the interpreter patn. If niaaenname 18 
present, the command is hidden as that; otherwise it is hidden with the name 
it had when exposed. 


® interp invokehidden path ?-global? hiddenName ?arg ...? 


Invokes the hidden command called niacenvame in the interpreter pan, passing 


328 


in all following arg values as arguments to the hidden command itself. 
® interp limit path limitType ?0ption? ?value? ... 
Configures the execution limit on the interpreter patn of type 1imitrype. 
® interp recursionlimit path ?newLimit? 
Queries or sets the recursion limit (maximum depth of nested command 
calling) for the interpreter pacn. Omitting newzimie queries the current limit, 
and providing newzimit Sets the limit. Note that Tcl independently imposes a 
hard limit based on the amount of stack space available. 


® interp share srcPath channelID targetPath 


Arranges for the channel called cnanneirp in the interpreter srcpatn to be also 
available with the same name in the interpreter target path. 


® interp transfer srcPath channelID targetPath 


Arranges for the channel called channeirp in the interpreter srcratn to be 
available with the same name in the interpreter targetratn. The channel is not 
subsequently available in the interpreter srcpatn. 


® rename old new 


Renames the command oa tO new, or deletes oa if new is an empty string. 
Returns an empty string. 

® time script ?count? 
Executes script count times and returns a string giving the average elapsed 
time per execution, in microseconds. count defaults to 1. 

® trace add command name ops scriptPrefix 
Establishes a trace on the command name such that scriptrrerix 18 Invoked 
whenever one of the operations given by ops is performed on name. ops Must 
consist of a list of one or both of the following words: aetete, rename. Returns 
an empty string. 

® trace add execution name ops scriptPrefix 
Establishes a trace on the command name such that scriptprerix 18 Invoked 
whenever one of the operations given by ops 1s performed during the 
execution Of name. ops must consist of a list of one or more of the following 
words: enter, leave, enterstep, leavestep. Returns an empty string. 


® trace add variable name ops scriptPrefix 
Establishes a trace on the variable name such that scriptprerix 18 invoked 
whenever one of the operations given by ops is performed on name. ops must 
consist of a list of one or more of the following words: array, reaa, write, 
unset. Returns an empty string. 
® trace info command name 
trace info execution name 


trace info variable name 


Returns a list describing each of the traces set on the command or variable 
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name. Each element is itself a two-element list; the first element is the list of 
operations that the trace watches, and the second element is the script prefix 
used by the trace. 
® trace remove command name ops scriptPrefix 

trace remove execution name ops scriptPrefix 

trace remove variable name ops scriptPrefix 
If there is a trace of the indicated type set on the command or variable name 
with the operations and script prefix given by ops and scriptprerix, the trace is 
removed, so that scriptprerix 18 never again invoked. Returns the empty 
string. If name does not exist, an error is thrown. 


® unknown cmd ?arg arg ...? 


This command is invoked by the Tcl interpreter whenever an unknown 
command name is encountered. cma is the unknown command name, and the 
args are the fully substituted arguments to the command. The result returned 
by unknown 1S returned as the result of the unknown command. 


15.2 Time Delays 


The aster command allows you to incorporate timing into your applications. 
It has two forms. If you invoke arter with a single argument, the argument 
specifies a delay in milliseconds, and the command delays for that number 
of milliseconds before returning. For example, 


after 500 


delays for 500 milliseconds before returning. This form of the aster 
command blocks, so your application cannot respond to events while the 
command is sleeping. In contrast, if you specify additional arguments, as in 
the command 


after 5000 {puts "Time's up!"} 


the arter command returns immediately without any delay. However, it 
concatenates all of the additional arguments exactly like the concat command 
and arranges for the resulting script to be evaluated after the specified 
delay. The script is evaluated in the global scope as an event handler, just 
like the scripts for widget bindings and file events. In the previous example, 
a message is printed on the standard output after 5 seconds. There may be 
any number of after scripts pending at once. 
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The after iaie command registers an idle callback: 
after idle script ?script ...? 


In this form, the script arguments are concatenated in the same manner as 
with concat, and the resulting script is run exactly once, the next time the 
event loop is entered and there are no events to process. This form of the 
after Command also immediately returns. 

The return value of the last two forms of the arter command is a unique 
identifier representing the registered script. You can pass it as an argument 
to the after cancer command to cancel the pending script if it has not yet 
executed. 


Note 


The last forms of the aster command require the event loop to be active 
to invoke the registered handlers. See Section 12.6 for more 
information on the event loop and event-driven programming. 


As an example of using the arter command in event-driven applications, this 
script uses after to build a general-purpose blinking utility: 


proc blink {w option valuel value2 interval} { 
$w config Soption $valuel 
after Sinterval [list blink $w Soption \ 
S$value2 $valuel S$interval)] 


} 


blink .b -bg red black 500 


The viinx procedure takes five arguments, which are the name of a widget, 
the name of an option for that widget, two values for that option, and a blink 
interval in milliseconds. The procedure arranges for the option to switch 
back and forth between the two values at the given blink interval. It does 
this by immediately setting the option to the first value and arranging for 
itself to be invoked again at the end of the next interval with the two option 
values reversed, so that option is set to the other value. The procedure 
reschedules itself each time it is called, so it executes periodically forever. 
plink runs “in background”: it always returns immediately, then gets re- 
invoked by Tk’s timer code after the next interval expires. This allows the 
application to do other things while the blinking occurs. 
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15.3 Time and Date Manipulation 


Tel’s cicck command provides a variety of time and date manipulation 
utilities. Many of Tcl’s time-related commands express time relative to the 
epoch time, which is defined as January 1, 1970, 00:00 UTC. 

The ciock seconas Command returns the current time expressed as a signed 
integer number of seconds since the epoch time, which is the most common 
representation of epoch-based time in Tel. The ciock miiiiseconas and clock 
microseconds Commands return the current epoch-based time in milliseconds 
and microseconds respectively. 


15.3.1 Generating Human-Readable Time and Date Strings 


The ciock format command accepts an integer number of seconds since the 
epoch time and returns a human-readable time and date string: 


clock format time ?-option value ...? 
clock format has a default format for the return value: 


clock format [clock seconds] 
= Fri Aug 29 13:05:00 PDT 2008 


If you include a -format option, the argument that follows is a string that 
specifies how the date and time are to be formatted. The string consists of 
any number of characters other than the percent sign (:) interspersed with 
any number of format groups, which are two-character sequences beginning 
with the percent sign. Tcl supports a large number of format groups, many of 
them added in Tel 8.5 for localization support. Table 15.1 lists the meanings 
of some of the more commonly used format groups. See the ciock reference 
documentation for a complete list. 


Table 15.1 Common ciocx Format Groups 
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group Meaning 


ta Abbreviated name of the day of the week 

%A Full name of the day of the week 

tb Abbreviated name of the month 

sh 

%B Full name of the month 

td Number of the day of the month, as two decimal digits 

$e Number of the day of the month, as one or two decimal digits, with a lead- 
ing blank for one-digit dates 

%H Two-digit number giving the hour of the day (00-23) on a 24-hour clock 

$I Two-digit number giving the hour of the day (12-11) on a 12-hour clock 

$j Three-digit number giving the day of the year (001-366) 

$k One- or two-digit number giving the hour of the day (0-23) on a 24-hour 
clock 

%1 One- or two-digit number giving the hour of the day (12-11) on a 12-hour 
clock 

$m Number of the month (01-12) with exactly two digits 

=M Number of the minute of the hour (00-59) with exactly two digits 

$N Number of the month (1-12) with one or two digits, with a leading blank 
for one-digit dates 

%p Part of the day in lower case, such as am or pm 

$P Part of the day in upper case, such as AM or PM 

ts Two-digit number of the second of the minute (00-59) 

&t Tab character 

$T Synonymous with $H:%M:%S 

su Number of the day of the week (1 = Monday, 7 = Sunday) 

tw Number of the day of the week (0 = Sunday ; 6 = Saturday ) 

ey Two-digit year of the century; the date is presumed to lie between 1938 
and 2037 inclusive 

34 Four-digit calendar year 

%z Current time zone, expressed in hours and minutes east (+hhmm) or west 
(-hhmm) of Greenwich 

%Z Current time zone’s name 

% Literal % character 

+ Synonymous with $a %b te %$H:%M:%S %Z %Y 


Here are some examples: 


set time [clock seconds] 

clock format $time -format "%d %b %yY" 
=> 29 Aug 2008 

clock format $time -format "$I:%M:%S %p" 
= 03:05:00 PM 


Starting in Tcl 8.5, you can also provide a -timezone option to request the time 
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zone in which the date and time are to be formatted. The time zone can be 
expressed in several standard formats; see the ciock reference documentation 
for details. 


clock format $time 
=> Fri Aug 29 15:05:00 CDT 2008 

clock format $time -timezone ":Europe/Berlin" 
= Fri Aug 29 22:05:00 CEST 2008 

clock format $time -timezone ":UTC" 
= Fri Aug 29 20:05:00 UTC 2008 


Tel 8.5 also introduced localization of the time and date strings. By default, 
clock format returns a time and date string localized according to the current 
system locale. By supplying the -1ccaie option, you can specify a different 
locale, and ciock format generates a localized time and date string 
appropriate to that locale. Many locales are supported by default; see the 
clock reference documentation for information on supplying your own 
localizations if they are not already provided by Tcl. 


clock format Stime -format "SA, %tB td %Y" -locale de 
=> Freitag, August 29 2008 

clock format $time -format "%A, *B *d %Y" -locale pt 
=> Sexta-feira, Agosto 29 2008 

clock format $time -format "%A, %B %*d %Y¥" -locale fr 
=> vendredi, aotit 29 2008 


15.3.2 Scanning Human-Readable Time and Date Strings 


The ciock scan command accepts a human-readable time and date string and 
returns an integer value representing the number of seconds since the epoch: 


clock format inputString ?-option value ...? 


For compatibility with versions of Tcl prior to 8.5, the c1ock scan command 
applies some heuristics to attempt to parse the string without guidance; for 
example: 


clock format [clock scan "3:37 pm"] 
=> Fri Oct 31 15:37:00 CDT 2008 

clock format [clock scan "August 29, 1965"] 
=> Sun Aug 29 00:00:00 CDT 1965 

clock format [clock scan "4:15 pm February 8, 2037"] 
=> Sun Feb 08 16:15:00 CST 2037 
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However, to reduce ambiguity in Tcl 8.5 and later, you should provide the - 
format Option tO clock scan followed by a string describing the expected 
format of the input. The string can consist of any number of characters other 
than the percent sign (:), interspersed with any number of format groups. 
The format groups are the same as supported for the ciock format Command 
described in the previous section. ciock scan raises an error if the string does 
not match the specified format: 


clock format [clock scan "Sept 9, 1961" -format "%B te, %Y"] 
=> Sat Sep 09 00:00:00 CDT 1961 
clock format [clock scan "20080829T142305" \ 
-format "tYytmtdTtHtMts" ) 
=> Fri Aug 29 14:23:05 CDT 2008 
clock scan "1:23am" -format "%tB" 
@ input string does not match supplied format 


Note 


In general, the ciock scan format group interpretation is more generous 
than that of ciock format. For example, sa results in a two-digit day of the 
month, with a leading o if necessary, with clock format; In contrast, it 
matches a one- or two-digit day, with optional leading space, with cock 
scan. Similarly, ss produces the full month name with ciock format, 
whereas ciock scan allows the month name in abbreviated or full form, 
or any unique prefix of either form. 


The ciock scan command in Tcl 8.5 and later also supports localized time and 
date representations. By default, the time and date string is interpreted 
according to the system locale. However, you can use the -iocaie option in 
combination with -format to specify an alternate locale for parsing the string: 


clock scan "Sexta-feira, Agosto 29 2008" \ 
-format "tA, *B td %Y" 

@ input string does not match supplied format 
clock scan "Sexta-feira, Agosto 29 2008" \ 
-format "tA, %B td %Y¥" -locale pt 

=> 1219986000 
clock scan "vendredi, aofit 29 2008" \ 
-format "tA, *B td %Y" -locale fr 

= 1219986000 


15.3.3 Performing Clock Arithmetic 
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For compatibility with versions of Tcl prior to 8.5, the c1ock scan command 
supports simple clock arithmetic. In addition to a small set of keywords 
such aS now, today, yesterday, aNd tomorrow, you can specify any combination of 
units of time to add or subtract; for example: 


clock format [clock scan "now"] 
=> Tue Jan 27 02:49:10 CST 2009 

clock format [clock scan "12:15pm yesterday"] 
= Mon Jan 26 12:15:00 CST 2009 

clock format [clock scan "tomorrow - 2 months + 3 weeks"] 
=> Fri Dec 19 00:00:00 CST 2008 


Tel 8.5 introduced the ciock aaa command to eliminate the ambiguity of the 
clock scan Command in clock arithmetic: 


clock add time Val ?count unit ...? ?-option value ...? 


The first argument to ciock aaa 18 an integer number of seconds relative to the 
epoch time. The remaining arguments are integers and keywords in 
alternation, where the keywords are chosen from seconds, minutes, hours, days, 
weeks, months, OF years OF any unique prefix of such a word. The integers 
specify the number of units to add to—or subtract from, in the case of a 
negative integer—the base time: 


set time [clock scan "2008-01-30 05:00:00" \ 
-format "%Y-%m-%$d $H:%M:%S"] 
clock format $time 
= Wed Jan 30 05:00:00 CST 2008 
clock format [clock add Stime 5 weeks] 
=> Wed Mar 05 05:00:00 CST 2008 
clock format [clock add $time 1 month] 
=> Fri Feb 29 05:00:00 CST 2008 
set time [clock scan {2004-10-30 05:00:00} \ 
-format {%Y-%m-%d %H:%M:%S}] 
clock format $time 
=> Sat Oct 30 05:00:00 CDT 2004 
clock format [clock add $time 1 day] 
=> Sun Oct 31 05:00:00 CST 2004 
clock format [clock add $time 24 hours) 
=> Sun Oct 31 04:00:00 CST 2004 


Note 
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The ciock aaa command attempts to handle gracefully situations such as 
the start or end of Daylight Savings Time and the change from Julian to 
Gregorian calendars. See the ciock reference documentation for 
complete information. 


15.4 Timing Command Execution 


The time command is used to measure the performance of Tcl scripts. It takes 
two arguments, a script and an optional repetition count: 


time {format "%d%s%f" 123 xyz 4.56} 100000 
= 3.85866 microseconds per iteration 


time executes the given script the number of times given by the repetition 
count (which defaults to 1), divides the total elapsed time by the repetition 
count, and returns a message similar to the preceding example, giving the 
average number of microseconds per iteration. The repetition count allows 
reasonably accurate measurements even when the clock resolution is less 
than ideal. 


Note 


In general, to make accurate timing measurements, experiment with the 
repetition count until the total time for the time command to run is a 
second or so. 


15.5 The inc: Command 


The info command provides information about the state of the Tcl interpreter 
through introspection. It has a rich set of options, which are discussed in the 
following sections. 


15.5.1 Information about Variables 
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Several of the into options provide information about variables. info exists 
returns a 1 or o value, indicating whether or not there exists a variable 
(including an array element) with a given name: 


set x 24 

info exists x 
— 8 J 

unset x 

info exists x 
=o. 

info exists env(PATH) 
= 1 


The options vars, globais, and iocais return lists of variable names that meet 
certain criteria. info vars returns the names of all variables accessible at the 
current level of procedure call; ingo giobais returns the names of all global 
variables, regardless of whether or not they are accessible; and info 1ocals 
returns the names of local variables, including arguments to the current 
procedure, if any, but not global variables. In each of these commands, an 
additional pattern argument may be supplied. If the pattern is supplied, only 
variable names matching that pattern (using the rules of string match) are 
returned. 

For example, suppose that the global variables gicba1i and gicbaiz have been 
defined and that the following procedure is being executed: 


proc test {argl arg2} { 
global globall 
set locall 1 
set local2 2 


} 


Executing the following commands within the procedure would produce the 
following results: 


info vars 
=> globall argl arg2 local2 locall 
info globals 
=> global2 globall 
info locals 
=> argl arg2 local2 locall 
info vars *al* 
= globall local2 localil 


In addition, the pattern argument to into vars may be preceded by a 
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namespace to list the variables defined in that namespace: 


namespace eval example { 
variable varl 
variable var2 
variable anotherVar 


} 


info vars example: :var* 
=> ::example::var2 ::example::varl 


15.5.2 Information about Procedures 


Another group of info options provides information about procedures. The 
command info procs returns a list of all the Tcl procedures that are defined in 
the current namespace. Like info vars, It takes an optional pattern argument 
that restricts the names returned to those that match a given pattern or selects 
another namespace to examine. info body, info args, aNd info defauit return 
information about the definition of a procedure: 


proc maybePrint {a b {c 24}} { 
if {$a < $b} { 


puts "c is $c" 


} 


info body maybePrint 
—_ 
if {$a < $b} { 
puts "c is $c" 


info args maybePrint 
zat Bie 

info default maybePrint a x 
= 0 

info default maybePrint c x 
=>_2 

set x 
=> 24 


info boay returns the procedure’s body exactly as it was specified to the proc 
command. info args returns a list of the procedure’s argument names, in the 
same order in which they were specified to proc. info default returns 
information about an argument’s default value. It takes three arguments: the 
name of a procedure, the name of an argument to that procedure, and the 
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name of a variable. If the given argument has no default value (for example, 
a In the preceding example), info aefauit returns o. If the argument has a 
default value (- in the preceding example), into aefauit returns i and sets the 
variable to hold the default value for the argument. 

As an example of how you might use the commands from the previous 
paragraph, here is a Tcl procedure that writes a Tcl script file. The script 
contains Tcl code in the form of proc commands that re-create all of the 
procedures in the global namespace of the interpreter. The file can then be 
sourced 1N some other interpreter to duplicate the procedure state of the 
original interpreter. The procedure takes a single argument, which is the 
name of the file to write: 


proc printProcs {file} { 
set £ [open $file w] 
foreach proc [info procs] { 
set argList {} 
foreach arg [info args $proc] { 
if {[info default $proc $arg default]} { 
lappend argList [list Sarg $default] 
} else { 
lappend argList [list $arg] 
} 


} 
puts $f [list proc $proc SargList \ 
{info body $proc}] 
} 


close Sf 


} 


info provides one other option related to procedures: info ieve1. If into ievei 
is invoked with no additional arguments, it returns the current procedure 
invocation level: o if no procedure is currently active, 1 if the current 
procedure was called from the top level, and so on. If into ievei 1S given an 
additional argument, the argument indicates a procedure level, and info 1eve1 
returns a list whose elements are the name and actual arguments for the 
procedure at that level. For example, the following procedure prints out the 
current call stack, showing the name and arguments for each active 
procedure: 


proc printStack {} { 
set level [info level] 
for {set i 1} {$i < $level} {incr i} { 
puts "Level $i: [info level $i]" 
} 
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15.5.3 Information about Commands 


The info commanas SUubcommand is similar to info procs except that it returns 
information about all currently visible commands, not just procedures. If 
invoked with no arguments, it returns a list of the names of all commands 
visible in the current namespace context. If an argument is provided, it is a 
pattern in the sense of string match With an optional namespace prefix (just as 
with info procs and info vars), and only command names matching that pattern 
(in the given namespace if the prefix is there) will be returned. 


info commands for* 
=> for format foreach 
namespace eval example { 
proc foo {} {return foobar} 
proc bar {} {return barfoo} 


} 


info commands example::* 
=> ::example::foo ::example::bar 


The command info cmdcount returns a number indicating how many commands 
have been executed in this Tcl interpreter. It may be useful during 
performance tuning to see how many Tcl commands are being executed to 
carry out various functions, and it is also a value that may be controlled 
using an interpreter resource limit (as discussed in Section 15.11.4). 

The command info script indicates whether a script file 1s currently being 
processed. If so, the command returns the name of the innermost nested 
script file that is active. If there is no active script file, info script returns an 
empty string. This command is used mostly for working out the location of 
files that are placed in the same directory as the script file, like this: 


set otherFile [file dirname [info script] ]/other.tcl 


Note 


You can also override the current script file name up until the end of 
the currently executing procedure by passing the new script file name 
as an argument to info script, which is used when writing customized 
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replacements for the source command. This is the way to perform 
preprocessing of a script before evaluation, but it is only rarely useful. 


The command info compiete 1S used when parsing input from a channel (such 
aS stdin) to determine whether a string represents a syntactically complete 
sequence of Tcl commands. This is used mainly when writing a handler that 
allows the execution of interactive scripts as part of the processing of a 
program; when tcisn 1s executing without a script argument, its main read- 
evaluate loop uses info complete to determine when to pass a string to the Tcl 
interpreter for evaluation. 


15.5.4 The Tcl Interpreter Version and Other Runtime Environment 
Information 


The info tciversion Command returns the version number for the Tcl 
interpreter in the form major.minor, Such as 8.5. Both major and minor are 
decimal strings. If a new release of Tcl contains only backward-compatible 
changes such as bug fixes and new features, its minor version number 
increments and the major version number stays the same. If a new release 
contains changes that are not backward-compatible, so that existing Tcl 
scripts or C code that invokes Tcl’s library procedures will have to be 
modified, the major version number increments and the minor version 
number resets to 0. The command info patchieve1 returns more detailed 
version information that indicates the exact patch level of the Tcl interpreter, 
such as s.5.3; this is usually useful only when submitting bug reports or 
determining whether to upgrade. 

The command info library returns the full path name of the Tel library 
directory. This directory holds standard scripts used by Tcl, such as a 
default definition for the unknown procedure described in Section 15.10. 

The command info hostname returns the host name of the machine on which the 
Tcl interpreter is running. Note that this command returns only the primary 
name of the machine. Some machines (especially server systems with 
multiple network connections) may have multiple names, and a more 
sophisticated approach to obtaining the name may be needed. 

The commands info nameofexecutable ANd info sharedlibextension respectively 
return the name of the executable that was used to invoke the Tcl interpreter 
and the standard shared library file name extension used on the platform on 
which the Tcl interpreter is running. info nameofexecutable 18 useful in 
situations where you want to invoke another Tcl interpreter as a separate 
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process vla exec OF open, and info sharedlibextension 18 useful when creating 
cross-platform Tcl scripts that use icaa to access extension modules written 
in programming languages like C. 


15.6 Tracing Operations on Simple Variables 


The trace command allows you to monitor the usage of a number of aspects 
of the Tcl interpreter, including variables. Such monitoring is called 
tracing. If a trace has been established on a variable, a Tcl command is 
invoked whenever the variable is read, written, or unset. Traces can be used 
for a variety of purposes, such as 
¢ Monitoring the variable’s usage (for example, by printing a message 
for each read or write operation) 
¢ Propagating changes in the variable to other parts of the system (for 
example, to ensure that a particular widget always displays the 
picture of a person named in a given variable) 
¢ Restricting usage of the variable by rejecting certain operations (for 
example, generating an error on any attempt to change the variable’s 
value to anything other than a decimal string) or by overriding 
certain operations (for example, re-creating the variable whenever it 
is unset) 
Here is a simple example that prints a message when either of two variables 
is modified: 


trace add variable color write pvar 
proc pvar {name element op} { 

upvar 1 $name x 

puts "Variable $name set to $x" 


} 


In this example, the trace command arranges to invoke the procedure pvar 
whenever the variable coior 1s written. The argument variabie specifies that a 
variable trace is being created, coior gives the name of the variable, write 
specifies a set of operations to trace (a list of any combination of reaa, write, 
and unset), and the last argument 1s a command to invoke. 

Whenever coior 18 modified, Tcl invokes pvar with three additional arguments 
appended: the variable’s name; the variable’s element name if it is an array 
element, or an empty string otherwise (the pvar procedure ignores this 
argument); and an argument indicating what operation was actually invoked. 
The operation argument is reaa when the variable is read, write when it is 
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written, and unset when the variable is deleted. For example, if the command 
set color purple 1S executed, Tcl evaluates the command pvar color {} write 
because of the trace. 

The pvar procedure does two things. First, the procedure uses upvar to make 
the variable’s value accessible inside the procedure as local variable «. 
Then it prints out the variable’s name and value on standard output. For the 
access in the preceding paragraph the following message would be printed: 


Variable color set to purple 


Write traces are invoked after the variable’s value has been modified but 
before returning the new value as the result of the write. The trace command 
can write a new value into the variable to override the value specified in 
the original write, and this value is returned as the result of the traced write 
operation. Read traces are invoked just before the variable’s result is read. 
The trace command can modify the variable to affect the result returned by 
the read operation. Tracing is temporarily disabled for a variable during the 
execution of read and write trace commands. This means that a trace 
command can access the variable without causing traces to be invoked 
recursively. 

If a read or write trace returns an error of any sort, the traced operation is 
aborted. This can be used to implement read-only variables, for example. 
Here is a script that forces a variable to have a positive integer value and 
rejects any attempts to set the variable to a non-integer value: 


trace add variable size write forceInt 
proc forceInt {name element op} { 
upvar 1 $name x ${name} old x_old 
if {!{regexp {*\d+$} $x]} { 
set x $x_old 
error "value must be a positive integer" 


} 


set x_old $x 


} 


By the time the trace command is invoked, the variable has already been 
modified, so if gorcernt wants to reject a write, it must restore the old value 
of the variable. To do this, it keeps a shadow variable with the suffix o1a to 
hold the previous value of the variable. If an illegal value is stored in the 
variable, forcemnt restores the variable to its old value and generates an 
error: 
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set size 47 


=.47 
set size red 

@ can’t set "size": value must be a positive integer 
set size 

=> 47 


You can use traces to create a read-only variable. The simplest way to 
implement this is to store the value to which the variable is to be reset as 
part of the trace callback itself; this is possible because the trace callback is 
really a script fragment and not just a command name. The additional 
argument provided when registering the trace becomes an additional 
argument to the callback procedure; for example: 


set pi [expr {4*atan(1) }] 
trace add variable pi write [list constant $pi] 
proc constant {value name element op} { 

upvar 1 $name var 

set var Svalue 

error "variable is a constant" 


} 


set pi 3 
@ can’t set "pi": variable is a constant 
Note 


When generating script fragments for callbacks and other deferred 
evaluations, it is highly advisable to use the 1ist command to do the 
generation as was just demonstrated. This applies the correct amount 
of quoting to ensure that the value is relayed to the callback procedure 
exactly as it was provided at the creation of the callback, without 
interference from the Tcl interpreter. 


It is legal to set a trace on a nonexistent variable; the variable continues to 
appear to be unset even though the trace exists. For example, you can set a 
read trace on an array, and then use it to create new array elements 
automatically the first time they are read. Unsetting a variable removes the 
variable and any traces associated with the variable, then invokes any unset 
traces for the variable. It is legal, and not unusual, for an unset trace to 
immediately reestablish itself on the same variable so that it can monitor the 
variable if it should be re-created in the future. 
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To delete a trace, invoke trace remove variable With the same arguments passed 
tO trace add variable. For example, the trace on coicr in the earlier example 
can be deleted with the following command: 


trace remove variable color write pvar 


If the arguments to trace remove variable do not match the information for any 
existing trace exactly, the command has no effect. 

The command trace info variable returns information about the traces 
currently set for a variable. It is invoked with an argument consisting of a 
variable name, as in the following example: 


trace info variable color 
=> {write pvar} 


The return value of trace info variable 18 a list, each of whose elements 
describes one trace on the variable. Each element is itself a list with two 
elements, which give the list of operations traces and the command for each 
trace. The traces appear in the result list in the order in which they are 
invoked. If the variable specified to trace info variable 18 an element of an 
array, only traces on that element are returned; traces on the array as a 
whole are not returned. 


Note 


It is possible to use traces to create very unclear code, such as making 
the whole world change when you read or write a variable. This is 
considered very poor style. If an operation may have significant side 
effects, it should (usually) be implemented as a command invocation. 


15.7 Tracing Array Variables 


With trace you can trace not only normal variables, but also array elements 
and whole arrays. Tracing an array element is exactly the same as tracing a 
simple variable, except that the variable name is split into two parts (the 
array name and the element name) when passed to the trace callback 
command; for example: 
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set a(length) 42 
trace add variable a(length) write pAry 
proc pAry {aName eName op} { 
upvar 1 $aName ary 
puts [format "Notice: %s(%s) has changed to %s" \ 
SaName $SeName Sary($eName) ] 
} 
incr a(length) 
=> Notice: a(length) has changed to 43 
43 


When tracing whole arrays, there are finer nuances. First, the read, write, 
and unset traces fire when any element of the array is accessed (according 
to the type of access), except for the case where the upvar command was 
used to create a link to an element of the traced array. Second, an additional 
type of trace is available to handle accesses that need to know the whole set 
of elements, such as when processing the array get OF array names Commands: 
the array trace type. This fires whenever the array is accessed as a whole; 
when it triggers, it never passes the name of an element. 


set a(b) c 
trace add variable a {read write array} pWholeAry 
proc pWholeAry {aName eName op} { 
puts "Traced: $op on ${aName} ($eName) " 
} 


append a(b) c 

Traced: write on a(b) 
ce 

array set a {c de f£} 
Traced: array on a() 
Traced: write on a(c) 
Traced: write on a(e) 
array get a {[a-c]} 
Traced: array on a() 
Traced: read on a(b) 
Traced: read on a(c) 
bivce cad 


YUU UY 


YUYY 


Note 


Array traces are used to implement the global env array. Those traces 
cause the array to be rebuilt every time it is written to or read from. 
This means that you are strongly advised to avoid using upvar to link a 
local variable to any element of the env array; always use giobai to bring 
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the whole array into scope. This re-creation behavior 1s also why 
accesses tO env are Slow; it is always more efficient to use some other 
mechanism when you do not actually need access to the environment 
variables. 


15.8 Renaming and Deleting Commands 


The rename command is used to change the command structure of an 
application. It takes two arguments: 


rename old new 


rename does just what its name implies: it renames the command that used to 
have the name o1a so that it now has the name new. It is an error if new already 
exists as a command when you invoke rename. 

You can also use rename to delete a command by invoking it with an empty 
string as the new name. For example, the following script removes event loop 
processing from an interpreter by deleting the relevant commands: 


foreach cmd {after fileevent update vwait} { 
rename $cmd {} 
} 


Any Tcl command may be renamed or deleted, including the built-in 
commands as well as procedures and commands defined by an application. 
Take care when renaming or deleting a built-in command, since it will break 
scripts that depend on the command (possibly including some other built-in 
commands), but in some situations it can be useful. For example, the exit 
command as defined by Tcl exits the process immediately. If an application 
wants to have a chance to clean up its internal state before exiting, 1t can 
create a “wrapper” around exit by redefining it: 


rename exit exit.old 

proc exit {{status 0}} { 
# application-specific cleanup 
B20 
exit.old $status 


} 


In this example, the exit command is renamed exit.cia and a new exit 
procedure is defined, which performs the cleanup required by the 
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application and then calls the renamed command to exit the process. This 
allows existing scripts that call exit to be used without change, while still 
giving the application an opportunity to clean up its state. 


15.9 Tracing Commands 


The trace command may be used to trace command-related events as well as 
variable-related events. By using trace aaa commana, you can track changes to a 
command’s name (using the rename Operation) and detect when the command 
is deleted (the acicte operation). This is particularly useful in situations 
where the command has associated with it some resources that should be 
deleted at the same time as the command. For example, the following 
procedure implements a simple logging system that closes the log file when 
the logging command is deleted: 


proc log {name filename} { 
set £ [open $filename a] 
interp alias {} $name {} logCommand $f 
trace add command $name delete [list logDone $f] 
return $name 


} 


proc logCommand {f args} { 
set now [clock seconds] 
set time [clock format Snow -format "%D %T: "] 
puts $f $time[join S$args " "] 


} 


proc logDone {f old new op} { 
puts "Renaming \"Sold\" to \"Snew\" (Sop) " 
close Sf 


} 


In this example, the 1og command creates a new command that logs to the 
given file by creating an interpreter alias (see Section 15.11.1 for more 
details) to the 1ogcommana Command that implements the logging command. To 
ensure that the file is closed in a timely fashion, the 10g command then adds a 
delete trace that ensures that the logging channel is disposed of when the 
command to write to it is destroyed. The command trace callback, 
implemented by 1ogpone, is invoked whenever the command is either deleted 
or renamed, as selected in the trace ada commana Invocation. The callback is 
invoked with three extra arguments: what the command was renamed from, 
what it is being renamed to (or the empty string in the case of deletion), and 
what operation is being performed. The following illustrates the command 
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in use: 


log example eg.log 

=> example 
example This is a message 
example This is another message 
rename example eg 
eg This is a third example 
rename example {} 


=> Renaming “eg" to "" (delete) 
read [open eg.log] 
=> 05/07/05 14:56:14: This is a message 


05/07/05 14:56:19: This is another message 
05/07/05 14:57:02: This is a third example 


This example also illustrates another important technique for working with 
traces: adding user-defined arguments to the trace callback. These 
additional arguments always come before the arguments added by the trace 
callback process. This is how togpone discovers what channel to close. 
Commands may also have their execution behavior traced using trace aaa 
execution, Which 1s particularly useful for debugging complex scripts. Four 
kinds of execution events may be traced; to receive notification of when a 
command is invoked, you should put an enter trace on it, and to find out what 
the command’s result is, you should put a icave trace on it. Finer-grained 
information about the execution of a command 1s also available. With the 
enterstep and icavestep execution traces it is possible to find out about all the 
command entry and completion behavior that happens during the execution 
of a command (this is most obvious during the processing of a procedure, 
but it can be applied to any other Tcl command as well). 

With enter and enterstep traces, two arguments are added to the callback 
command. The first is the list of fully substituted arguments to the command, 
and the second is the operation that triggered the trace callback. With 1eave 
and iecavestep traces, four arguments are appended; as with enter traces, the 
first argument is the list of fully substituted arguments, and the last argument 
is the operation name. However, the second argument is the return code just 
as would be seen by catch at that point (o for success, i for error, etc.), and 
the third argument is the result of the command. 
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proc tracer {args} {puts TRACE:S$args} 
proc subemd {s} {string length $s} 
proc demo {args} { 

expr {[llength $args]+[subcmd $args] } 
} 


trace add execution demo {enter leave} tracer 
demo abe 
=> TRACE: {demo a b c} enter 
TRACE: {demo a bc} 0 8 leave 
8 
demo "another demo" 
=> TRACE: {demo {another demo}} enter 
TRACE: {demo {another demo}} 0 15 leave 
15 
trace remove execution demo {enter leave} tracer 
trace add execution demo {enterstep leavestep} tracer 
demo abc 
= TRACE: {expr {[llength Sargs]+[subcmd Sargs]}} enterstep 
TRACE: {llength {a b c}} enterstep 
TRACE: {llength fa b c}} 0 3 leavestep 
TRACE: {subcemd {a b c}} enterstep 
TRACE: {string length {a b c}} enterstep 
TRACE: {string length {a b c}} 0 5 leavestep 
TRACE: {subcmd {a b c}} 0 5 leavestep 
TRACE: {expr {[llength Sargs]+[subcmd Sargs]}} 0 8 leavestep 
8 


Like variable traces, trace info 1S used to discover information about 
command and execution traces, and trace remove can be used to delete them. 


trace info execution demo 
> f{fenterstep leavestep} tracer} 


15.10 Unknown Commands 


The Tcl interpreter provides a special mechanism for dealing with unknown 
commands. If the interpreter discovers that the command name specified in a 
Tcl command does not exist, it checks for the existence of a command named 
unknown. If there is such a command, the interpreter invokes unknown instead of 
the original command, passing the name and arguments for the nonexistent 
command to unknown. For example, suppose that you type the following 
commands: 


set x 24 
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createDatabase library $x 


If there is no command called createpatabase, the following command is 
invoked: 


unknown createDatabase library 24 


Notice that substitutions are performed on the arguments to the original 
command before unknown 1s invoked. Each argument to unknown consists of one 
fully substituted word from the original command. 

The unknown procedure can do anything it likes to carry out the actions of the 
command, and whatever it returns is returned as the result of the original 
command. For example, the following procedure checks to see if the 
command name is an unambiguous abbreviation for an existing command; if 
so, it invokes the corresponding command: 


proc unknown {name args} { 
set cmds [info commands Sname*] 


if {[llength $cmds] != 1} { 
error “unknown command \"Sname\"" 
} 


uplevel 1 $cmds Sargs 


} 


Note that when the command is re-invoked with an expanded name, it must 
be invoked using upieve1 so that the command executes in the same variable 
context as the original command. 
The Tcl script library includes a default version of unknown that performs the 
following functions, in order: 
1. If the command is a procedure that is defined in a library file, source 
the file to define the procedure, then re-invoke the command. This is 
called autoloading, described in Chapter 14. 
2. If a program exists with the name of the command, use the exec 
command to invoke the program. This feature is called autoexec. 
For example, on a Unix system you can type is as a command, and 
unknown WIIl invoke exec 1s to list the contents of the current directory. 
If the command does not specify redirection, autoexec arranges for 
the command’s standard input, standard output, and standard error to 
be redirected to the corresponding channels of the Tcl application. 
This is different from the normal behavior of exec, but it allows 
interactive programs such as more and vi to be invoked directly from 
a Tcl application. 
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3. If the command name has one of several special forms such as ::, 
compute a new command using history substitution and invoke it. If, 
for example, the command is ::, the previous command is invoked 
again. See Chapter 16 for more information on history substitution. 

4. If the command name is a unique abbreviation for an existing 
command, the abbreviated command name is expanded and the 
command is invoked again. 


Note 


The last three actions are intended as conveniences for interactive use, 
and they occur only if the command was invoked interactively. You 
should not depend on these features when writing scripts. For example, 
you should never use autoexec in scripts; always use the exec command 
explicitly. 


If you do not like the default behavior of the unknown procedure, you can write 
your own version or modify the library version to provide additional 
functions; the apparent nature of the Tcl language can be greatly changed 
through this. If you do not want any special actions to be taken for unknown 
commands, you can just delete the unkown procedure, in which case errors 
occur whenever unknown commands are invoked. 


Note 


The one feature of the autoexec system that is generally useful is the 
command auto execox, Which takes the name of an external command that 
you might want to run with exec and returns a list of words to use with 
exec that describe how to actually do it. This includes searching the pars 
for the program, adding suitable code for invoking the shell if it was a 
shell internal command rather than a program, and so on. For example, 
on Windows the start command is actually a shell internal, but it is 
extremely useful for opening many different types of files, just as in 
Windows Explorer. So you could use it like this to open a saved web 


page: 


exec {*}[auto_execok start] example.html 
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15.11 Slave Interpreters 


Slave interpreters are Tcl interpreters that are children of some other 
interpreter (called the master). They are used in cases where there is a need 
to evaluate a Tcl script in a context that is substantially different from that of 
the main Tcl program, such as 

¢ Processing untrusted code 

¢ Handling a plugin mechanism for a larger program that does not 

expose the details of the main body of the application 

¢ Creating a friendlier API for configuring an application 

* Isolating executions of some code from each other 

¢ Limiting the resources that may be used for a particular operation 
Slave interpreters’ variables are independent of the variables of the master 
interpreter or any other slave interpreters, with the notable exception of the 
shared global env array. This makes it easier to keep different spaces of 
variables apart. 
For example, you could have a configuration file format for your program 
without any danger that temporary variables used in the configuration file 
will interfere with the operation of the main program. Or you could have a 
chess game system where the state of the board and the rules of the game are 
enforced by the master interpreter, but each player’s code is in an 
independent slave interpreter, making it easy to show that the players are not 
interfering with each other. 
Slave interpreters are manipulated using the inters command. It is possible 
to nest slave interpreters within other slave interpreters, and the 
subcommands of the inters command indicate what interpreter they are 
manipulating by giving a path as a list of interpreter names, starting at the 
current interpreter. The slave interpreters are all completely independent 
from each other except for the global env array, which is normally shared. 
A slave interpreter is created (in the current thread if threading is enabled) 
using the interp create command, which takes an optional interpreter name. 
Scripts may then be evaluated in this interpreter using interp evai, and the 
interpreter can then be deleted with interp delete. 


Note 
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Using interp evai does not start a separate thread of execution. You can 
have multiple interpreters per thread, just as you can have multiple 
threads per OS process. Interpreters provide script-level isolation and 
different execution and global variable contexts. Parallel execution can 
be added through the use of multiple threads, which requires a threaded 
build of Tcl and the use of the rmreaa extension. Full isolation requires 
the use of multiple processes and interprocess communication, with all 
the overhead that implies. 


As you can see from the following example, a slave interpreter makes 
creating an application-specific language easy: 


set slave [interp create] 
=> interpd 
interp eval $slave rename expr calculate 
interp eval $slave rename value set 
interp eval $slave rename incr advance 
interp eval $slave { 
value x 3 
calculate {1 + 2 + $x + [advance x] + 5} 


} 
=> 25 
interp delete $slave 


When you create a slave interpreter, a command with the same name is also 
created. This allows you to invoke many operations directly, and to delete 
the interpreter by deleting the command. This means that the previous 
example could have been written like this: 


set slave [interp create] 
=> interp0 
S$slave eval rename expr calculate 
Sslave eval rename value set 
S$slave eval rename incr advance 
$slave eval { 
value x 3 
calculate {1 + 2 + $x + [advance x] + 5} 


} 


=> 15 
rename $slave {} 


15.11.1 Command Aliases 


355 


Sometimes it is necessary for scripts running in slave interpreters to be able 
to trigger the running of commands in their masters. For example, a network 
server configuration script will want to tell the server how to configure 
itself, even if it does not have the power to directly run the configuration 
code itself. This powerful feature is enabled by setting up an alias command 
in the slave that triggers the running of a command in the master using interp 
alias. You can get the list of aliases defined on an interpreter by using the 
interp aliases Command, and individual alias configurations can be obtained 
by using interp alias With fewer arguments than would be necessary to define 
an alias. 


interp create configurator 
interp alias configurator service {} initNamedService 
interp alias configurator usePort {} setServicePort 
interp alias configurator dump {} parray config 
proc initNamedService {name} { 
global servName 
set servName Sname 
} 
proc setServicePort {port} { 
global servName config 
if {!({string is integer -strict $port]} { 
return -code error \ 
"\"S$port\" is not an integer" 
} 
set config($servName) $port 
} 
interp eval configurator { 
service http 
usePort 80 
service "http-alt" 
usePort 8080 
dump 
} 
=> config (http) = 80 
config(http-alt) = 8080 
interp eval configurator { 
service {Whale watching! } 
usePort {Key West} 


} 


@ “Key West" is not an integer 


As a convenience, the per-slave command created when you create the 
slave interpreter has an aiias subcommand, though this allows only the 
definition of aliases from the slave interpreter into the master. (The full 
interp alias Command has a wider repertoire, including allowing aliases to 
be defined from one slave interpreter to another.) This means that the 
definition of the service, useport, aNd aump aliases from the previous example 
could have been done like this: 
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configurator alias service initNamedService 
configurator alias usePort setServicePort 
configurator alias dump parray config 


Aliases can even be defined within an interpreter by using an empty string 
for the interpreter name, which is useful for defining one command in terms 
of another: 


interp alias {} print {} puts stdout 
interp alias {} printError {} puts stderr 
print "This message goes to standard output" 
printError "and this one goes to standard error!" 


15.11.2 Safe Slave Interpreters and Hidden Commands 


One of the most important uses for slave interpreters is the parsing of Tcl 
scripts that are not trusted by the master interpreter. Examples of this 
include the parsing of Tcl code that is embedded within a web page, e-mail 
message, or some other context where the creator of the code is not 
necessarily known. Tcl provides a mechanism for handling this situation 
called a safe interpreter. Safe interpreters are slave interpreters that have a 
special flag set at creation time and that hide all their unsafe commands (for 
example, exec, open, socket, source) $O that they may not be called unless 
explicitly authorized to do so by the master interpreter. This mechanism, 
analogous to the way that an operating system handles the security of 
processes, is a very strong mechanism because there is no way to perform 
any state-changing operation within the Tcl language without executing a 
command. Although a safe interpreter can change its internal state, such as 
by creating procedures or setting variables, by default no commands are 
exposed in the safe interpreter for interacting with its master or the system 
executing the application. And unlike normal slave interpreters, safe slaves 
do not have access to the env variable and do not have a predefined unknown 
command (described in Section 15.10). 

You create safe interpreters by passing the -sare flag to interp create. You then 
use them exactly like any other slave interpreter, though the default set of 
commands is somewhat more restricted: 
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set safe [interp create -safe] 
=> interp0d 
interp eval $safe { 
file delete -force /home 
} 


@ invalid command name "file" 


A master interpreter should expose more dangerous behavior only in a 
controlled fashion to the safe interpreter using aliases. This allows access 
to specific parts of the behavior of a command without opening up access to 
all parts of it: 


interp alias $safe file {} safeFile 
proc safeFile {subcommand args} { 
switch -- $subcommand { 
dirname - extension - rootname - tail { 
return [file $subcommand {*}Sargs] 


} 


default { 
return "unknown subcommand \"Ssubcommand\"" 


} 
} 
} 


interp eval $i { 
file extension example.tcl 
} 


—— Pa ee! 
interp eval $i { 
file delete -force /home 
} 


@ unknown subcommand "delete" 


Another common example of selectively exposing access to prohibited 
commands within a safe interpreter is controlled access to the source 
command. You very well might want to source files or load packages from a 
safe interpreter, but by default the source command is not exposed in a safe 
interpreter. 

When the unsafe functionality is removed from a safe interpreter during its 
creation, the unsafe commands are not actually deleted. Instead, the 
interpreter hides them. The master interpreter may invoke hidden commands 
using the interp invokenidden COMmand, as can be seen in the following 
example. This implements a safer version of the source command that checks 
to see whether the file that is to be sourced is really a Tcl script file in the Tel 
library, otherwise refusing and claiming that the file does not exist: 
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interp alias $i source {} safeSource $i 

proc safeSource {slave filename} { 
# Get rid of elements like .. from the name 
# Very important in real code! 
set fullFilename [file normalize $filename] 


# Get the parts of the filename to examine 
set dir [file dirname $fullFilename] 
set ext [file extension $fullFilename] 


# Perform the safety check 
if {[string first [info library] $dir] != 0 || 
$ext ne ".tcl"} { 
return -code error \ 
“unknown file \"$filename\"" 


} 


# Really source the file 
return [interp invokehidden $slave \ 
source $fullFilename] 


} 


The master interpreter may use the interp nice and interp expose commands to 
manipulate the set of commands hidden and exposed by a slave interpreter, 
modifying the profile of code that may run successfully within that safe 
interpreter. In the following example the pwa command has been exposed so 
that code executing in the safe slave can discover its current directory, and 
the vwait and upaate commands have been hidden so the event loop cannot be 
entered: 


# Expose [pwd] to make a low-priority information leak 
interp expose $i pwd 

# Hide the ways to run the event loop 

interp hide $i update 

interp hide $i vwait 


Note 


While safe interpreters may create their own slave interpreters by 
default, all the interpreters that they create are forced to be safe 
interpreters, and many of the subcommands of the interp command are 
not available. Many extensions to Tcl also restrict themselves in safe 
interpreters. For example, Tk permits the use of only some of its 
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widgets from within a safe interpreter, blocking access to anything that 
could be used to obscure the enclosing application, and it also prevents 
the script from having access to things like system-wide configuration 
options or the clipboard. 


15.11.3 Transferring Channels between Interpreters 


By default, slave interpreters do not have access to their parents’ I/O 
channels. If an interpreter wishes to give access to a channel to one of its 
Slaves, it should use interp share OF interp transfer. interp share allows a 
second interpreter to use a channel at the same time as the interpreter that 
created the channel (both interpreters must close the channel for the file, 
socket, or pipeline to actually be closed), and interp transfer gives access to 
a channel from one interpreter to another without keeping it in the source 
interpreter. In both cases, the channel has the same name in the target 
interpreter as in the source interpreter. 

This can be useful in cases where you want to allow the script running in the 
child interpreter to open a file, but you do not want the script to know where 
that file is, or even that it is necessarily a file at all: 


set slave [interp create] 
=> interpd 
interp alias $slave openCurrentLogfile {} openLog $slave 
proc openLog {slave} { 
global loggingHost loggingPort 
set chan [socket $loggingHost $loggingPort] 
interp transfer {} $chan $slave 
return $chan 
} 
interp eval $slave { 
set £ [openCurrentLogfile] 
puts $f "script running" 
close $f 


15.11.4 Placing Limits on an Interpreter 


Every interpreter has a limit on the depth of recursive evaluations it can 


perform! This is so that procedures that accidentally call themselves in an 
unbounded fashion do not cause the interpreter to crash, but instead fail 
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gracefully with a catcnable error and have an informative stack trace 
available: 


proc recursive {} { 
puts "again and" 
recursive 


} 
recursive 
=> again and 
again and 
again and 
again and 
again and 


1. Note that there is a separate hard limit on the depth of recursion that is 
imposed by the underlying size of the process’s stack. 


again and 
again and 
again and 
again and 


@ too many nested evaluations (infinite loop?) 


The default limit is usually large enough for most programs, but some highly 
recursive programs require a much larger limit, and highly paranoid 
programmers dealing with safe interpreters may wish to set a much smaller 
limit. The limit can be queried and set using the interp recursionlimit 
command: 


# Read the current recursion limit 

set depth [interp recursionlimit $i] 

# Compute the new recursion limit (half the old one) 
set newDepth [expr {$depth / 2}] 

# Set the new limit on the interpreter 

interp recursionlimit $i $newDepth 


A number of other limits on execution can also be enabled through the interp 
limit Command, allowing a master interpreter to guarantee that a slave 
spends only a limited amount of effort carrying out some operation. The 
interp limit Command also provides a framework for setting up traps that 
trigger when the limits are exceeded so that a master interpreter can decide 
whether to permit the slave to execute further. See the reference 
documentation for the interp command for more details. Still other things can 
be controlled relatively easily through the master interpreter, such as the 
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number of open sockets and the total size of files being written to. 
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16. History 


This chapter describes Tcl’s history mechanism. In applications where you 
type commands interactively, the history mechanism keeps track of recent 
commands and makes it easy for you to re-execute them without having to 
retype them from scratch. You can also create new commands that are slight 
variations on old commands without having to completely retype the old 
commands—to fix typographical errors, for example. Tecl’s history 
mechanism provides many of the features available in the Unix csn, but not 
with the same syntax in all cases. 


Note 


TkCon is a replacement for the standard console that comes with Tk. 
Among its many features is a sophisticated command history and 
editing functionality. You can use the arrow keys to cycle between 
commands in the history, interactively edit retrieved commands, and 
execute the result. TkCon also retains the command history across 
multiple sessions. See Appendix B for more information on TkCon and 
how to obtain it. 


16.1 Commands Presented in This Chapter 


History is implemented by the history command. Only a few of the most 
commonly used history features are described in this chapter; see the 
reference documentation for more complete information. 

* history 
A shortcut for nistory info. 

* history clear 
Erases the history list, resetting the event numbers. The current keep limit is 
retained. 

® history info ?count? 
Returns a formatted string giving the event number and command for each 
event on the history list. If count 1s specified, only the most recent count 
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events are returned. 
* history keep count 
Changes the size of the history list so that the count most recent events will 
be retained. The initial size of the list is 20 events. 
* history nextid 
Returns the number of the next event that will be recorded in the history list. 
* history redo ?event? 


Re-executes the command recorded for event and returns its result. 


16.2 The History List 


Each command that you type interactively is entered into a history list. Each 
entry in the history list is called an event; it contains the text of a command 
plus a serial number identifying the command. The command text consists of 
exactly the characters you typed, before the Tcl parser performs 
substitutions for s, 1, and so on. The serial number starts at : for the first 
command you type and increments for each successive command. 
Suppose you type the following sequence of commands to an interactive Tcl 
program: 

set x 24 

set y [expr {$x*2.6}] 

incr xX 


At this point, the history list contains three events. You can examine the 
contents of the history list by invoking nistory with no arguments: 


history 
= 1 set x 24 
2 set y fexpr {$x*2.6}] 
3 incr x 


4 history 


The value returned by nistory 1s a human-readable string describing what’s 
on the history list, which also includes the history command itself. The result 
Of nistory 18 intended to be printed out, not to be processed in Tcl scripts; if 
you want to write scripts that process the history list, you’ll probably find it 
more convenient to use other history options described in the reference 
documentation, such as nistory event. 

The history list has a fixed size, which 1s initially 20. If more commands 
than that have been typed, only the most recent commands are retained. You 
can change the size of the history list with the nistory keep command: 
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history keep 100 


This command changes the size of the history list so that in the future the 100 
most recent commands are retained. 


16.3 Specifying Events 


Several of the options of the nistory command require you to select an event 
from the history list. Events are specified as strings with one of the 
following forms: 
¢ Positive number—selects the event with that serial number. 
¢ Negative number—selects an event relative to the current event. -1 
refers to the last command, -2 refers to the one before that, and so on. 
¢ Anything else—selects the most recent event that matches the string. 
The string matches an event either if it is the same as the first 
characters of the event’s command or if it matches the event’s 
command using the matching rules for string match. 
Suppose that you had just typed the three commands from Section 16.2. The 
command incr x can be referred to as event -1 or 3 OF inc, and set y [expr 
(sx*2.6}] Can be referred to as event -2 or 2 or «2+. If an event specifier is 
omitted, the default is -1. 


16.4 Re-executing Commands from the History List 


The history redo command retrieves a command and re-executes it just as if 
you had retyped the entire command. For example, after just the first three 
commands from Section 16.2 are typed, the command 


history redo 


replays the most recent command, which is incr x; 1t increments the value of 
variable x and returns its new value (2c). If an additional argument is 
provided for history redo, 1t selects an event as described in Section 16.3; for 
example, 


history redo | 
= 24 


replays the first command, set x 24. 
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16.5 Shortcuts Implemented by unknown 


The basic nistory commands are quite bulky; in the previous example, it took 
more keystrokes to type the nistory command than to retype the command 
being replayed. Fortunately there are several shortcuts that allow the same 
functions to be implemented with fewer keystrokes: 
Replays the last command; same aS nistory redo. 

* levent 
Replays the command given by event; Same aS history redo event. 

® *old*new 
Retrieves the last command, replaces all occurrences of cia with new, and 
executes the resulting command. 
The last shortcut is convenient for correcting typographical errors: 


set x "200 illimeters" 
=> 200 illimeters 
“i11*mill 
= 200 millimeters 


Keep in mind that Tcl’s substitution shortcut replaces a// occurrences of the 
old string: 
set x "out and about" 
=> out and about 
“out “in 


=> in and abin 


All of these shortcuts are implemented by the unknown procedure described in 
Section 15.10. unknown detects commands that have the forms described here 
and invokes the corresponding history commands to carry them out. 


Note 


If your system doesn’t use the default version of unknown provided by 
Tcl, these shortcuts may not be available. 


16.6 Current Event Number: history nextia 
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The command nistory nextia returns the number of the next event to be 
entered into the history list: 


history nextid 
= 3 


It is most commonly used in interactive applications to generate prompts 
that contain the event number. 
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17. An Introduction to Tk 


Tk is a toolkit package that allows you to create graphical user interfaces by 
writing Tcl scripts. Tk extends the built-in Tcl command set described in 
Part I with additional commands for creating user interface elements called 
widgets, arranging them into interesting layouts on the screen using 
geometry managers, and connecting them to each other with the enclosing 
application. Although Tk was developed to work with Tcl, other dynamic 
languages such as Perl, Python, and Ruby have adapted Tk to give these 
languages the ability to create graphical user interfaces. The commands and 
descriptions here apply to those languages as well, but the syntax is 
different. This part of the book describes Tk’s Tcl commands. 

Like Tcl, Tk is implemented as a C library package that can be included in 
C applications, and it provides a collection of functions that can be invoked 
from an application to implement new widgets and geometry managers in C. 
The library functions are discussed in the reference documentation. 

This chapter introduces the basic structures used for creating user interfaces 
with Tk, including the hierarchical arrangements of widgets that make up 
interfaces and the main groups of Tcl commands provided by Tk. Later 
chapters go over the individual facilities in more detail. All of the examples 
in this part can be run with wisn, the windowing shell that was introduced in 
Chapter 1, or with any Tcl-based application by including the command 


package require Tk. 


17.1 A Brief Introduction to Windowing Systems 


Windowing systems provide facilities for manipulating windows on 
displays using a keyboard and mouse. The mouse is used to move a pointer 
around on the screen, and it also contains one or more buttons and possibly 
a scroll wheel for invoking actions. Each screen displays a hierarchical 
collection of rectangular windows, starting with a root window (usually 
called a desktop) that covers the entire area of the screen, as shown in 
Figure 17.1. The root window may have any number of child windows, each 
of which is called a toplevel window. An application typically manages 
several toplevel windows, one for each of the application’s major panels 
and dialogs. Toplevel windows may have children of their own, which may 
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also have children, and so on. The descendants of toplevel windows are 
called widgets or internal windows, and they may be nested to any depth. 
Widgets are used for individual controls such as buttons, scrollbars, or text 
entries and for grouping other widgets together. 


Figure 17.1 Each screen contains a hierarchical collection of overlapping 
windows. 


Toplevel windows 


Internal windows 


Events are sent to notify applications of user actions such as key presses, 
pointer motions, and button presses. Each event identifies what occurred 
(for example, the pointer just passed into a window) and provides 
additional information about the event such as the window where the event 
occurred, the time when it occurred, the position of the pointer, and the state 
of the mouse buttons. Events are also generated for structural changes, such 
as window resizes and deletions, and to notify applications that they must 
redraw windows, such as when one window moves so that it no longer 
obscures another window. 

Windowing systems do not require windows to have any particular 
appearance or behavior. An application can draw anything it likes in any 
window, and it can respond to events in any way that it pleases. Thus, it is 
possible to implement many different appearances and modes of interaction. 
The lowest-level interface with a windowing system provides no support 
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for any particular look and feel, nor does it provide built-in controls such as 
buttons or menus. It is up to application-level toolkits to provide these 
features. The Tk toolkit implements a portable library of configurable 
widgets that can fit into any look-and-feel environment. In this regard, Tk is 
unique in that it uses the native toolkit where appropriate. This allows an 
application to be written once in Tcl/Tk and run on multiple platforms, 
taking on the look and feel of the local environment. 

A common element of all windowing systems is a window manager, also 
called a desktop environment. The window manager allows the user to 
manipulate toplevel windows in a uniform way for all applications. It 
displays a decorative frame around each toplevel window and provides 
controls within the frame so that users can interactively move, resize, 
iconify, and deiconify windows. The decorative frame also displays a title 
for the toplevel window. Many different window managers exist. On some 
systems, like Mac OS X and Microsoft Windows, there is only one by 
default, but on Unix and Linux systems, there are many to choose from. Each 
window manager may have different decorations and controls, but only one 
window manager exists for a given display at a given time. The examples in 
this book use a variety of window managers or desktop environments to 
demonstrate Tk’s versatility and portability in all these environments. 
Applications must communicate with both the windowing system and the 
window manager. The application communicates with the windowing 
system to create windows, draw on them, and receive events. It 
communicates with the window manager to specify titles, preferred 
dimensions, and other information for its toplevel windows. 

The three primary windowing systems that Tk supports are X, for Unix and 
Linux operating systems; Microsoft Windows; and Apple’s Mac OS X, also 
known as Aqua. For additional information on these windowing systems, 
search the web for Xorg, Microsoft User Interface Design and 
Development, or Apple Human Interface Guidelines, respectively. 


17.2 Widgets 


Tk uses low-level drawing APIs to implement a ready-made set of controls, 
which are commonly called widgets. Figure 17.2 shows examples of button, 
entry, and scrollbar widgets. Each widget is a member of a class that 
determines its appearance and behavior. For example, widgets in the button 
class display a text string or image. Different buttons may display their 
strings or images in different ways (for example, with different fonts and 
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colors), but each one displays a single string, image, or combination. Each 
button also has a Tel script associated with it, which is invoked if mouse 
button | (the left button on a three-button mouse) is pressed and released 
when the pointer is over the widget. Different button widgets may have 
different scripts associated with them to implement different operations. 
When you create a widget, you select its class and provide additional class- 
specific options, such as a string or image to display or a script to invoke. 


Figure 17.2 Examples of widgets: (a) a button widget; (b) an entry widget; 
(c) a scrollbar widget 


“a 
(a) 
(c) 
‘Sample text| 
(b) 
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Each Tk widget is implemented using one window.! As with windows, 
widgets are nested in hierarchical structures. A widget can contain any 
number of children, and the widget tree can have any depth. Widgets such as 
buttons that have meaningful behavior for the user are usually at the leaves 
of the widget tree; the non-leaf widgets are usually just containers for 
organizing and arranging the leaf widgets. 


1. The terms widget and window are used interchangeably in this book and 
in the reference documentation. 


Each widget or window has a textual name such as .a.b.c. Widget names are 
similar to the hierarchical path names for files, except that . 1s used as the 
separator character instead of , or \. The name . refers to the topmost 
widget in the hierarchy, which is called the main window. The name .a.».c 
refers to a widget - that is a child of widget .2.», which in turn is a child of 
.a, Which is a child of the main window. 

Figure 17.3 shows how a window is composed. The window is shown in 
(a) as it appears on the screen, with decorations provided by the windowing 
system. The hierarchical structure of the widgets is shown in (b). An 
exploded view of the screen is shown in (c) to clarify the widget structure. 
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The topmost widget in the hierarchy (.) contains three children: a menu 
across the top, a scrollbar along the right side, and a listbox filling the 
remainder. The menu bar contains two children of its own, a File menu on 
the left and a Help menu on the right. Each widget has a name that reflects 
its position in the hierarchy, such as .menu.neip for the Help menu. 


Figure 17.3 Window composition 


ra 
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17.3 Applications, Toplevel Widgets, and Screens 
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In Tk the term application refers to a single widget hierarchy (a main 
widget and its descendants), a single Tcl interpreter associated with the 
widget hierarchy, plus all the commands provided by that interpreter. Each 
application has its own widget hierarchy, so the name . refers to the main 
window or root window within the application. Normally an application 
runs in a single process, but Tk also allows a single process to manage 
several applications with separate widget hierarchies, one per Tcl 
interpreter. Tk does not require or provide any particular support for 
multithreading but may be used in a multithreaded environment, provided 
that all Tk commands and operations for a given window hierarchy are 
handled in a single thread and interpreter. 

The main widget for each application occupies a toplevel window, so it is 
decorated and managed by the window manager. Most of the other widgets 
of an application use internal windows. The topieve1 widget class is used to 
create additional toplevel windows so that the window manager can 
manipulate them independently. A toplevel widget differs from an internal 
widget in that its window is a child of the root window for its screen, 
whereas the window for an internal widget is a child of the window for the 
widget’s parent in the Tk hierarchy. Toplevel widgets are typically used as 
containers for panels and dialogs, as shown in Figure 17.4. In this example 
the dialog box .aig is a toplevel widget, as is the main widget. Figure 
17.4(a) shows how the widgets appear on the screen, and (b) shows Tk’s 
widget hierarchy for the application. 


Figure 17.4 Toplevel widgets 


(b) 
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17.4 Scripts and Events 


A Tk application is controlled by two kinds of Tcl scripts: an initialization 
script and event handlers. The initialization script is executed when the 
application starts. It creates the application’s user interface, loads the 
application’s data structures, and performs any other initialization needed 
by the application. Once initialization is complete, the application enters an 
event loop to wait for user interactions. Whenever an event occurs, such as 
the user invoking a menu entry or moving the mouse, a Tcl script is invoked 
to process that event. These scripts are called event handlers; they can 
invoke application-specific Tcl commands to enter an item into a database, 
modify the user interface (for example, by posting a dialog box), and do 
many other things. Some event handlers are created by the initialization 
script, but event handlers can also be created and modified by other event 
handlers; for example, an event handler for a menu might create a new 
dialog box along with new event handlers for the dialog. 

Most of the Tcl code for a Tk application is in the event handlers. Complex 
applications may contain hundreds of event handlers, and the handlers may 
create other panels and dialogs that have additional event handlers. Tk 
applications are therefore event-driven. There is no well-defined flow of 
control within the application’s scripts, since there is no single task for the 
application to perform. The application presents a user interface with many 
features, and the user decides what to do next. All the application does is 
respond to the user’s actions. The event handlers implement the responses; 
event handlers tend to be short, and they are mostly independent of each 
other. 


17.5 Creating and Destroying Widgets 


Tk provides four main groups of Tcl commands: for (1) creating and 
destroying widgets, (2) arranging widgets on the screen, (3) communicating 
with existing widgets, and (4) interconnecting widgets within and between 
applications. This section and the three following sections introduce the 
groups of commands to give you a general feel for Tk’s features. All of the 
commands are discussed in more detail in later chapters. 

To create a widget, you invoke a command named after the widget’s class: 
putton for button widgets, scroiisar for scrollbar widgets, and so on. These 
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commands are called class commands. For example, the following 
command creates a button that displays the text press me! 


button .b -text "Press me" -command {puts Ouch! } 


All class commands have a form similar to this. The command’s name 1s the 
name of a widget class. The first argument is the path name for the new 
widget, .» in this case. The command will create the widget and its 
corresponding window. The widget name is followed by any number of 
pairs of arguments, where the first argument of each pair specifies the name 
of a configuration option for the widget, such as -text OF -commana, and the 
second argument specifies a value for that option, such as press me OF {puts 
ouch!}. Each widget class supports a different set of configuration options, 
but many options, such as -goregrouna, are used in the same way by different 
classes. Values need not be specified for every option supported by a 
widget; Tk provides defaults for the unspecified options. For example, 
buttons support about 35 different options but only 2 were specified in the 
preceding example. Chapter 18 describes many of the most common 
configuration options. 

To delete a widget, you invoke the aestroy command: 


destroy .menubar 


This command destroys the widget named .menubar and all of its descendants, 
if there are any. 


17.6 Geometry Managers 


Widgets don’t determine their own sizes and locations on the screen; 
geometry managers carry out this function. Each geometry manager 
implements a particular style of layout. Given a collection of widgets to 
manage and some controlling information about how to arrange them, a 
geometry manager assigns a size and location to each widget. For example, 
you might tell a geometry manager to arrange a set of widgets in a vertical 
column. The geometry manager then positions the widgets so that they abut 
and do not overlap. If a widget should suddenly need more space (for 
example, because its font was changed to a larger one), the widget notifies 
the geometry manager and the geometry manager moves other widgets to 
preserve the column structure. 
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The second of the four main groups of Tk commands consists of those for 
communicating with geometry managers. Tk currently contains three 
geometry managers plus three widgets that can manage embedded widgets. 
The main geometry manager for Tk is the grid manager, which works by 
arranging widgets into rows and columns. The other primary geometry 
managers in Tk are the packer, which works by packing a series of widgets 
sequentially around the edges of a cavity, and the placer, which provides 
simple fixed or relative placements. Additionally, the window manager 1s 
used to manage toplevel windows in conjunction with the desktop 
environment. The canvas, text, and panedwindow widgets have an internal 
geometry manager for embedded widgets. Chapter 21 describes the 
geometry managers in more detail. 

When you invoke a class command like button, the new widget does not 
appear immediately on the screen. It appears only after you ask a geometry 
manager to manage it. If you want to experiment with widgets before 
reading the full discussion of geometry managers, you can make a widget 
appear by invoking the cgria command with the widget’s name as its 
argument. This sizes the widget’s parent so that it is just large enough to 
hold the widget and arranges the widget so that it fills the space of its 
parent. If you create other widgets and grid them in a similar fashion, the 
grid manager arranges them in a column inside the parent, making the parent 
just large enough to accommodate them all, as shown in Figure 17.5. The 
following script creates two button widgets and arranges them in a vertical 
column with the first widget above the second: 


button .top -text "Top button" 
button .bottom -text "Bottom button" 
grid .top 

grid .bottom 


Figure 17.5 Arranging widgets in a window 
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( Top button ) 


( Bottom button ) 


17.7 Widget Commands 
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Whenever a new widget is created, Tk also creates a new Tcl command 
with the same name as the widget. This command is called a widget 
command, and the set of all widget commands (one for each widget in the 
application) constitutes the third major group of Tk commands. After the 
button COMmand was executed in Section 17.5, a widget command whose 
name is .» appeared in the application’s interpreter. This command exists as 
long as the widget exists; when the widget is deleted, the command is 
deleted, too. 

Widget commands are used to communicate with existing widgets. Here are 
some commands that could be invoked after the button command from 
Section 17.5: 


.b configure -command runCommand 
.b invoke 


The first command changes the callback made when the button is pressed, 
and the second command invokes the button’s command as if the user had 
clicked mouse button | over the widget. In widget commands, the command 
name is the name of the widget, and the first argument specifies an action to 
invoke on the widget. Some actions, like configure, take additional 
arguments; the nature of these arguments depends on the specific action. 


Note 


The terms action, widget command, and widget subcommand are used 
interchangeably throughout this book. For example, the phrase “the 
configure Widget command” really means “the configure action for the 
widget command.” 


The set of widget commands supported by a given widget is determined by 
its class. All widgets in the same class support the same set of widget 
commands, but different classes have different command sets. Some 
common actions are supported by multiple classes. For example, every 
widget class supports a configure widget command, which can be used to 
query and change the widget’s configuration options. 


17.8 Commands for Interconnection 
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The fourth group of Tk commands is used for interconnection. These 
commands are used to make widgets work together, to make them work 
cooperatively with the objects defined in the application, and to allow 
different applications sharing the same display to work together in 
interesting ways. 

Some of the interconnection commands are implemented as event handlers. 
For example, each button has a -commana option that specifies a Tcl script to 
invoke whenever mouse button | is clicked over the widget. Scrollbars 
provide another example of interconnection via event handlers. Each 
scrollbar is used to control the view in some other widget. When you click 
in the scrollbar or drag its slider, the view in the associated widget should 
change. This connection between widgets is implemented by specifying a 
Tcl command for the scrollbar to invoke whenever the slider is dragged. 
The command invokes a widget command for the associated widget to 
change its view. Other kinds of event handlers and event generation are 
described in Chapter 22. 

Some of the Tk widgets support a model-view-controller paradigm via a 
link to a Tcl variable. The value of the variable is used to define the 
widget’s text content or state. The checkbutton and radiobutton widgets 
actually require it for the widgets to work correctly. This feature is 
discussed in more detail in Chapter _18; also see the reference 
documentation for information on the -textvariabie and -variabie options 
provided on several widgets. 

Another form of interconnection is selection management. The selection is a 
highlighted piece of information on the screen, such as a range of text or a 
graphic. Tk provides a way to manage the selection in conjunction with the 
window manager so that applications can claim ownership of the selection 
and retrieve its contents from whichever application owns it. Chapter 25 
discusses the selection in more detail and describes Tk’s se1ection command. 
Chapter 26 describes Tk’s window manager command, wm, which is used for 
communicating with the window manager. The window manager acts as a 
geometry manager for toplevel windows, and the wm command can be used to 
make specific geometry requests of the window manager, such as “Don’t let 
the user make this window smaller than 80 pixels tall.” In addition, wm can 
be used to specify a title to appear in the window’s decorative border, a 
title and/or icon to display when the window is iconified, and many other 
attributes. 

At any given time the keystrokes typed for an application are directed to a 
particular widget, regardless of the mouse cursor’s location. This widget is 
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referred to as the focus widget or the widget having focus. Chapter _27 
describes the focus command, which is used to query about the current focus 
widget or to change the focus. Chapter 27 also describes grabs, which 
restrict keyboard and mouse events so that they are processed only in a 
subtree of the widget hierarchy. Windows outside the grab subtree are 
blocked from receiving any events until the grab is released. Grabs are used 
to disable parts of an application and force the user to deal immediately 
with a high-priority window such as a dialog box. 

Finally, Chapter 12 describes several ways for programs to communicate. 
The sena command is one way, specific to Tk, providing a general-purpose 
means of communication between applications. You can use sena to issue an 
arbitrary Tcl command to any Tk application on the display. 
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18. A Tour of the Tk Widgets 


This chapter introduces the classic widget classes implemented by Tk, 
which have been around since nearly the beginning of Tcl. They provide a 
cross-platform means to create user interfaces for your scripts. In addition, 
these classic widgets provide an easy way to add a user interface to an 
existing application, whether written in Tcl or not. With the ability to embed 
a Tcl interpreter within applications, you can extend your applications with 
a graphical user interface. Or you can use Tcl’s commands to drive a 
command-line application and use Tk widgets to introduce a user interface. 
In addition to the classic Tk widgets, recent years have seen the 
development of a set of themed widgets. Themes aim to separate widget 
functionality from the visual look of the widgets. In addition, themes allow 
for much better-looking widgets. The classic Tk look comes from the early 
era of Windows 95 and Motif on Unix; the themed widgets provide a more 
modern appearance, as well as a unified and modifiable look and feel. This 
chapter introduces the older classic Tk widgets. The next chapter covers the 
themed widgets. 

The main advantage to using themed widgets is to give a native look to a Tk 
application by selecting the style that fits the user’s current desktop 
environment. While Tk uses native widgets on Microsoft Windows and Mac 
OS X for scrollbars, checkbuttons, and radiobuttons, X-based classic Tk 
widgets have the basic Motif look. The themed widgets provide a variety of 
styles that match a variety of desktop environments available on Unix 
operating systems. New styles can also be added to make a themed 
application instantly fit into new desktop environments. The newer themed 
widgets are still evolving and don’t yet provide the full functionality of the 
older widgets. There are also some classic Tk widgets that don’t have a 
themed counterpart. However, you can combine classic and themed widgets 
in the implementation of your application’s interface. 


Note 


As of Tk 8.5, the widget class commands for creating classic Tk 
widgets are defined in the ::tx namespace; for example, ::tx::button 
creates a classic Tk button widget. In contrast, the widget class 
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commands for creating themed widgets are defined in the .::ttx 
namespace. For backward compatibility with existing scripts, the 
classic Tk widget class commands are imported automatically into the 
global namespace. This may be discontinued in a future release of Tk, 
in which case you could add a namespace import Command to your existing 
scripts to explicitly import the needed widget class commands. See 
Chapter 10 for more information on namespaces. 


Note 


The examples in this chapter use the gria command to arrange widgets, 
though you don’t need to understand the operation of the gria commands 
yet in order to understand the examples. Chapter 21 discusses the gria 
command in detail. 


18.1 Widget Basics 


Each classic Tk widget class is defined by three things: its configuration 
options, its widget commands, and its default bindings. Configuration 
options represent most of the state information for most widgets; they 
include things such as the colors, fonts, and text to display in a button widget 
and the Tcl script to invoke when the user clicks on the widget. All of the 
widgets in a class support the same configuration options. Different classes 
may have different options, but many options, such as -foregrouna and -font, 
are supported by many different classes. The configuration options for a 
widget may be specified when the widget is created and modified later with 
the configure Widget command. Default values can be specified using the 
option database (see Chapter 28). 

The second thing that defines a widget class is its widget command. As 
described in Section 17.7, one widget command exists for each widget in an 
application, and it is used to invoke actions in the widget. The actions 
provided by a widget command vary from class to class, but some actions 
are supported by several classes. For example, every class supports a 
configure action for changing the widget’s configuration options. For more 
complex widgets such as menus and listboxes, the widget’s internal state is 
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too complex to represent entirely with configuration options, so additional 
actions are provided to manipulate the state. For example, the widget 
command for menus provides actions to create and delete entries and to 
modify existing entries. 

The third thing that defines a widget class is its default bindings. The default 
bindings give widgets their behavior by causing Tcl scripts to be evaluated 
in response to user actions. Tk creates the default bindings by evaluating an 
initialization script stored in the Tk library directory; the script invokes the 
pina command described in Chapter 22. This means that the behaviors are 
not hard-coded into the widgets; you can modify the behavior of individual 
widgets or entire classes using the »ina command. The descriptions in this 
chapter correspond to the default behaviors. 

Tk currently defines the widget classes listed in Table 18.1. In addition to 
these classic widgets, the themed widget extension provides 18 themed 
widgets (see Chapter 19). The themed widgets provide additional functions 
and an updated look and feel, so when there is a choice, these widgets 
should be preferred over the classic Tk widgets for new application 
development. 


Table 18.1 Classic Tk Widget Classes 


button canvas checkbutton entry frame 
label labelframe listbox menu menubutton 
panedwindow : radiobutton scale scrol lbar spinbox : 
text toplevel 


This chapter gives an overview of most of the classic widget classes along 
with the most commonly used configuration options; canvas and text widgets 
are described separately in Chapter 23 and Chapter 24, respectively. This 
chapter does not explain every feature of every widget; for that you should 
refer to the reference documentation for the individual widget classes. If you 
wish to see additional examples of widget usage besides those in this 
chapter, you should run the demonstration scripts in the Tk distribution. In 
particular, the script wiaget contains examples of various widgets. You can 
run the wiaget demo using the following commands from a wisn interpreter: 

cd $tk_library 

cd demos 


source widget 


The wiaget script creates a window with many links to examples of various 
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Tk widgets. For each example, you can see a live demonstration of the 
widget as well as view the example source code. 


18.2 Frames 


Frames are the simplest widgets; they appear as colored rectangular regions 
and can have three-dimensional borders. As you will see later, frames 
typically serve as containers for grouping other widgets. Most of the non- 
leaf widgets in an application are frames. Frames are particularly important 
for building nested layouts with geometry managers; when used in this way, 
frames are often invisible to the user. This is discussed in Chapter 21. 
Frames are also used to generate decorations such as a block of color or a 
raised or sunken border around a group of widgets. Frames have no default 
behavior; they do not normally respond to the mouse or keyboard. 


18.2.1 Relief Options 


Frames support only a few configuration options, and most of these are 
supported by all basic widget classes. For example, the -re1ier and - 
borderwidth Options can be used to specify a three-dimensional border. The - 
relief Option determines the appearance of the border and must have one of 
the values raisea, sunken, flat, groove, OF riage. Tk draws widget borders with 
light and dark shadows to produce the different effects. For example, if a 
widget’s relief is raisea, Tk draws the top and left borders in a lighter color 
than the widget’s background and it draws the lower and right borders in a 
darker color. This makes the widget appear to protrude from the screen. An 
example of each -reiier setting is shown in Figure 18.1. 


Figure 18.1 Five frames with different relief configurations 


e028 Wish Shell 


a 


The source for this example follows. Each frame sports a darker color to 
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help distinguish the frame boundaries. 


set c -l 

foreach relief {raised sunken flat groove ridge} { 
frame .$relief -width 15m -height 10m -relief $relief \ 
-borderwidth 4 -background {dark grey} 
grid .$relief -column [incr cc] -row 0 -padx 2m -pady 2m 


} 


. configure -background {light grey} -padx 12 -pady 12 


The three-dimensional appearance of a theme widget comes from the theme, 
so you normally don’t need to set the relief setting on ttx::frame or other 
themed widgets. 


18.2.2 Screen Distance Options 


Several commonly used configuration options take screen distances as 
values. For example, the -porderwiatn Option controls the border width, the - 
width and -neight options can be used to specify the dimensions of a frame, 
and widgets such as text provide an -insertwiatn option for specifying the size 
of the insertion cursor. Screen distances can be specified either in pixels or 
in absolute units independent of the screen resolution. A distance consists of 
an integer or floating-point value followed optionally by a single character 
giving the units. If no unit is specified, the units are pixels. Otherwise the 
unit is designated by one of the following characters: 

* -—centimeters 

* i—inches 

* »—millimeters 

* »—printer’s points (1/72 inch) 
For example, a distance specified, as 2.2c is rounded to the number of pixels 
that most closely approximates 2.2 centimeters; the number of pixels may 
vary from screen to screen. The code that produced Figure 18.1 contains 
examples of screen distance options specified in millimeters and pixels. 
Screen distances are used for other purposes in Tk besides widget 
configuration options. One example is the -paax and -paay options to the gria 
command, which are used in the code that produced Figure 18.1 to leave 
extra space around each of the frame widgets. 


18.3 Color Options 
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The -packgrouna option determines the background color of a widget and also 
the shadow colors used in its border. The value of the -vackgrouna option may 
be specified either symbolically or numerically. A symbolic color value is a 
name such aS white OF rea OF seacreen2. Tk defines a large number of symbolic 
color values available on all platforms based on standard Unix color 
values. Color names are not case-sensitive: biack 18 the same aS siack and 
piack. Refer to the colors page of the reference documentation for a list of 
valid color names. Windows and Mac OS X platforms also support a set of 
aliased colors, such as activeBorder aNd systemwindowZoay, Which refer to user 
preference settings in these environments. These symbolic color values are 
also documented in the colors reference documentation. 

Colors can also be specified numerically in terms of their red, green, and 
blue components. Four forms are available, in which the components are 
specified with 4-bit, 8-bit, 12-bit, or 16-bit values: 


#RGB 

#RRGGBB 
#RRRGGGBBB 
#RRRRGGGGBBBB 


Each x, c, or s in these examples represents one hexadecimal digit of red, 
green, or blue intensity, respectively. The first character of the specification 
must be +, and the same number of digits must be provided for each 
component. If fewer than four digits are given for each component, they 
represent the most significant bits of the values. For example, #327 is 
equivalent to #3000a0007000. A value of all is represents “full on” for that 
color, and a value of 0 represents “off.” Thus, #000 1s black, #00 is red, #s£0 
is yellow, and #<¢¢ 1s white. 


Note 


If you specify a color other than black or white for a monochrome 
display, Tk uses black or white instead, depending on the overall 
intensity of the color you requested. Furthermore, if you are using a 
color display and all of the entries in its color map are in use (e.g, 
because you’re displaying a complex image on the screen), Tk treats 
the display as if it were monochrome. 


Virtually every basic widget class supports a -backgrouna option, and most 
widget classes support additional color options. For example, most widget 
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classes provide a -foregrouna option that determines the color of the text or 
graphics displayed in the widget. For theme widgets, the color options are 
defined by the theme. 


18.3.1 Synonyms 


Tk provides special short forms for a few of the most commonly used 
options. For example, -»a is a Synonym for -borderwidth, -bg 1S a Synonym for 
background, and -s, is a synonym for foreground. 


18.4 Toplevels 


Toplevel widgets are identical to frames except that they occupy toplevel 
windows, whereas frames occupy internal windows. Toplevels are 
typically used as the outermost containers for an application’s panels and 
dialog boxes. The main widget for an application is also a toplevel. When 
creating a new toplevel widget, you can use the -menu option to specify a 
menu widget to use as that window’s menu bar. The menu bar is displayed 
along the top of the window as part of the window manager’s decoration. 
On Mac OS X, the menu bar is displayed across the top of the screen. 
Chapter 26 provides more information on managing toplevels. 


18.5 Labels 


A label widget displays information to the user. A label widget may display 
a text string, a bitmap, an image, or a combination of text and a bitmap or 
image. Labels provide several additional configuration options for 
specifying what to display in the widget; Figure 18.2 is an example of a 
compound label generated by the following script: 
label .label -text "No new mail" -bitmap \ 
o$tk_ library/demos/images/flagdown.xbm \ 


-compound top 
grid .label 


Figure 18.2 The label widget displaying a bitmap and a text string 
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No new mail 


18.5.1 Text Options 


Most widgets that display simple text strings, like labels, provide two 
options for specifying the string. Ifa -text option is specified, as for .1abe1 1n 
the script for Figure 18.2, its value is the string to display in the widget. If 
instead you specify the -textvariabie Option, you can set its value to the name 
of a variable referenced from the global namespace. The -textvariabie option 
causes the widget to display the contents of the variable; whenever the 
variable changes, the widget resizes and/or redisplays itself to reflect the 
new value. 

The text string displayed by the label can contain embedded newline 
characters, in which case the label displays multiple lines of text. The - 
justify Option determines how the lines align with each other, and you can 
Set 1t to 1eft, center, OF right. 


Note 


A common practice is to use namespace variables in -textvariable 
references to prevent polluting the global namespace with too many 
variables. This requires using fully qualified namespace names (e.g., 


::Application:: country) ‘ 


Here is a simple example that uses -textvariable! 


proc watch {name} { 
toplevel .watch 
label .watch.label -text "Value of \"S$name\": " 
label .watch.value -textvariable $name 
grid .watch.label .watch.value -pady 12 
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This procedure will create a new toplevel widget and grid two labels 
inside it to display the name of a global variable and its value. For example, 
the following script can be invoked to create the panel shown in Figure 


18.3(a): 


set country Japan 
watch country 


Figure 18.3 The -+extvariabie option ties a widget’s value to a variable. 


8 © Owatch ’ @A@ watch 


Value of "country": Japan Value of "country": Great Britain 


(a) (b) 


Figure 18.3(b) shows how the display changes if the following command is 
invoked to change the variable’s value: 


set country "Great Britain" 


18.5.2 Font Options 


The -sont option specifies a font to use when displaying text in a widget. Tk 
uses a Standard font description of family size style. .., Where size and style 
are optional. Some example font descriptions are 

{Times 12 bold italic} 

{Helvetica 14 bold} 


{Courier 10 normal} 


Other description formats are supported as well, including standard X11 
font descriptions. The Tk sone command can be used to create and manage 
application fonts; it is discussed in more detail in Chapter 20. 


Note 
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For almost all widget classes, all characters within a widget use the 
same font and style. The text widget, on the other hand, can display 
multiple lines of text and apply different fonts and other display 
characteristics to substrings. See Chapter 24 for more information on 
the text widget. 


18.5.3 Image Options 


Labels and many other widgets can display images in the form of bitmaps or 
images instead of text. A bitmap is a picture with two colors, foreground 
and background. Bitmaps are specified using the -pitmap option, whose 
values may have two forms. If the first character of the value is e, the 
remainder of the value is the name of a file containing a bitmap in X bitmap 
file format. Thus -vitmap @face.xbm Specifies a bitmap contained in the file 
face.xbm. The script for Figure 18.2 specifies a bitmap as 
@$tk library/demos/images/flagdown.xbm. This refers to one of the bitmaps in the 
library of demonstrations that is included with the Tk distribution (the 
variable tx iibrary’s library files). 

If the first character of the value isn’t e, the value must be the name of a 
bitmap defined internally. Tk defines a few internal bitmaps itself that are 
used in message dialogs, and individual applications may define additional 
ones. 

The -vitmap option determines only the pattern of is and os that make up the 
bitmap. The foreground and background colors used to display the bitmap 
are determined by the -foregrouna and -packgrouna Options for the widget. This 
means that the same bitmap can appear in different colors at different places 
in an application, and the colors of a given bitmap may be changed by 
modifying the -foreground and -backgrouna Options. 

Images are created using the Tk image create command. Some example images 
are shown in Figure 18.4. Images are objects created from image data 
directly, or from various file formats. Tk directly supports the XBM, XPM, 
GIF, and PPM/PGM formats. Tk extensions such as Img and TkMagick 
provide support for just about all other image file formats commonly in use. 
Images are specified using the -image option as shown here: 


image create photo hiker -file hiker.gif 

toplevel .images 

label .images.1 -text hiker -image hiker -compound top 
grid .images.1 
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Figure 18.4 Sample images using the Tk image command 
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Images are shared among all widgets that reference them. Any change to an 
image is reflected everywhere it appears on the screen. Images are 
discussed in more detail in Chapter 20 on fonts and images. 


18.5.4 Compound Options 


Labels may display both an image and text, as shown in Figure 18.2. The 
position of the image relative to the text is specified with the -compouna 
option. The values top, bottom, left, right, aNd center Will place the image 
above, below, left of, right of, and centered on the text respectively. A value 
Of none displays only the image if an -image OF -bitmap option is used; 
otherwise only the text is displayed. 


18.6 Labelframes 


While frames are used to organize widgets into groups, the labelframe 
widget provides all the features of the frame widget plus, as the name 
suggests, a label and a border ring, as shown in Figure 18.5. The label may 
be placed in any of the eight compass directions around the frame using the - 
labelanchor Option. The labelframe is a common element found in dialogs and 
panels. The following script generated the labelframe figure shown: 


proc watch {name} { 
toplevel .watch -padx 14 -pady 15 
labelframe .watch.1f -text "Value of \"S$name\"" 
label .watch.1lf.value -textvariable $name 
grid .watch.1lf.value -padx 3 -pady 3 
grid .watch.1f -sticky nsew 
} 
set country "United States of America" 
watch country 
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Figure 18.5 An example ofa labelframe widget 
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Value of "country" 
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United States of America 


18.7 Buttons 


Buttons, checkbuttons, radiobuttons, and menubuttons make up a family of 
widget classes with similar characteristics. These classes have all of the 
features of labels, and they also respond to the mouse. When the pointer 
moves over a button, the button lights up to indicate that something will 
happen if a mouse button is pressed; a button in this state is said to be 
active. It is a general property of Tk widgets that they light up if the pointer 
passes over them when they are prepared to respond to button presses. 
Buttons become inactive when the pointer leaves them. 

If mouse button 1 is pressed when a button widget 1s active, the widget’s 
appearance changes to make it look sunken, as if a real button had been 
pressed. When the mouse button is released, the widget’s original 
appearance is restored. Furthermore, when the mouse button is released, the 
widget evaluates its -commana option as a Tcl script. Figure 18.6 is an 
example that can be created with a script like the following: 


button .ok -text OK -command 

button .apply -text Apply -command 

button .cancel -text Cancel -command cancel 

button .help -text Help -bitmap question -command help 
grid .ok .apply .cancel .help 


Figure 18.6 Four button widgets 
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The procedures ox, apply, cancel, aNd hep are invoked when the user clicks on 
one of the buttons with the mouse; the code for these procedures is not 
provided here. In this example the -commana options are all single words, but 
in general they can be arbitrary scripts. 


18.7.1 Checkbuttons 


Checkbuttons are used for making binary choices such as enabling or 
disabling underlining or grid alignment; see Figure 18.7 for an example. 
Checkbuttons are similar to buttons except for two things. First, when you 
click mouse button 1 over a checkbutton, a global variable toggles in value 
between o and 1. The variable name is specified to the widget with the - 
variable Option. Second, the checkbutton displays a rectangular selector to 
the left of its text or bitmap. When the variable’s value is :, the selector is 
displayed as a check mark and the checkbutton is said to be selected; 
otherwise the selector box appears empty. Each checkbutton monitors the 
value of its associated variable, and if the variable’s value changes (e.g., 
because of a set command), the checkbutton updates the selector display. 
Checkbuttons provide additional configuration options for specifying the 
color of the selector and for specifying “off’ and “fon” values other than o 
and 1. 


Figure 18.7 Three checkbuttons 
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The buttons in Figure 18.7 are created by the following script. Each 
checkbutton toggles a particular variable between o and i, and its selector 
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Square indicates the current value of the variable (the variables »o1ia and 
underline are currently 1, italic 1S 0). The -anchor options cause the buttons to 
left-justify their text and selectors as described in Section 18.15.3. 


checkbutton .bold -text Bold -variable bold -anchor w 
checkbutton .italic -text Italic -variable italic -anchor w 
checkbutton .underline -text Underline \ 

-variable underline -anchor w 
grid .bold -sticky ew 
grid .italic -sticky ew 
grid .underline -sticky ew 


In some situations a checkbutton may be used to represent the state of 
multiple items. In these cases it is useful for the widget to display a state 
that represents both “on” and “off.” Take the preceding example where the 
bold, italic, aNd underline State of some text is represented. If the text had a 
mix of bold and normal characters, the button would need to represent both 
states. This is done using the tristate value for the widget, as shown in 
Figure 18.8. The tristate value causes the widget to display an alternate 
mark that represents this “mixed” condition. You specify the tristate value 
with the widget’s -tristatevalue option: 


.bold configure —tristatevalue 3 
set bold 3 


Figure 18.8 Example checkbutton in “tristate” or “mixed” state 
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18.7.2 Radiobuttons 


Radiobutton widgets provide a way to select one of several mutually 
exclusive options, much as the radio buttons in cars are used to select one of 
several stations. Several radiobuttons work together to control a single 
global variable. Each radiobutton provides a -variabie option to name the 
variable and a -vaiue option to specify a value for the variable; when you 


398 


click on the widget, it sets the variable to the given value. For example, 
Figure 18.9 shows a collection of radiobuttons that are used to select a font 
family from among several alternatives. Each radiobutton displays a round 
selector to the left of its text or bitmap and lights up the selector when it is 
selected (i.e., whenever the variable’s value matches its -vaiue option). Each 
radiobutton monitors the variable and turns its selector on or off when the 
variable value changes. The user can select one of four values for the global 
variable font by clicking on a button. In the figure the selector circle for the 
courier Widget is marked to indicate that it is selected (the variable 
currently has the value courier). 


radiobutton .times -text Times -variable font \ 
-value times -anchor w 

radiobutton .helvetica -text Helvetica -variable font \ 
-value helvetica -anchor w 

radiobutton .courier -text Courier -variable font \ 
-value courier -anchor w 

radiobutton .symbol -text Symbol -variable font \ 
-value symbol -anchor w 

grid .times -sticky ew 

grid .helvetica -sticky ew 

grid .courier -sticky ew 

grid .symbol -sticky ew 


Figure 18.9 Four radiobuttons 
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The radiobutton also supports a tristate value and display, similarly to the 
checkbutton, as shown in Figure 18.10. 


Figure 18.10 The tristate appearance of the radiobutton widget 
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18.7.3 Menubuttons 


The menubutton widget creates a button that, when pressed, posts a menu. 
Menus are discussed in more detail in Section 18.12. Like the other button 
widgets, the menubutton can be configured with any combination of text and 
image and also has an indicator. Figure 18.11 demonstrates a menubutton 
used to select an alignment option by using radiobutton menu entries. The 
following script creates this menubutton: 


menubutton .mb -width 9 -textvariable justify 

set m [menu .mb.menu -tearoff 0] 

-mb configure -menu $m 

$m add radiobutton -value Left -variable justify \ 
-label Left 

$m add radiobutton -value Center -variable justify 
-label Center 

$m add radiobutton -value Right -variable justify \ 
-~label Right 

$m add radiobutton -value Justified -variable justify \ 
-label Justified 

label .1 -text Alignment: 

grid .1 -row 0 -column 0 -sticky e 

grid .mb -row 0 -column 1 -sticky w 

set justify Left 


Figure 18.11 Example menubutton as it appears normally (a) and when 
posted (b) 
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18.8 Listboxes 


A listbox is a widget that displays a collection of strings and allows the user 
to select one or more of them. For example, the listbox in Figure 18.12 
displays the names of the available font families. If a listbox contains too 
many entries to display at once, as in Figure 18.12, it displays as many as 
will fit in the window. Scrollbars can be associated with listboxes as 
described in Section 18.9, and listboxes can be scrolled horizontally if their 
entries are too wide for their windows. 


Figure 18.12 A listbox that displays all font families available in the system 
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The entries in a listbox can be managed in two ways. One way is through the 
configure option -1istvariapie. This option takes the name of a global or 
namespace variable that contains a list of values. As the variable is 
modified, the listbox updates to display the contents of the list. The 1istnox 
widget command also provides several actions for manipulating entries, 
such as insert for adding new entries, ceiete for deleting entries, and get for 
retrieving entries. Modifying the variable value using the variety of Tcl list 
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commands is often easier than using the listbox widget commands directly. 
The script implementing the listbox in Figure 18.12 manipulates the 
associated list variable to fill the listbox: 


listbox .fonts -listvariable ::fontlist 
grid .fonts 
set ::fontlist \ 
{[lsort -dictionary [font families) ] 
bind .fonts <Double-Button-1> { 
$W configure -font [list [%W get [tW curselection]] 12] 
5 


} 


Listboxes are usually configured so that the user can select an entry by 
clicking on it with mouse button 1. In some cases the user can also select a 
range of entries by pressing and dragging with button 1. Both single-select 
and multiple-select modes are supported. (See the reference documentation 
for more information.) Selected entries appear in a different color or 
possibly some other style or effect. Once the desired entries have been 
selected, the user typically uses them by invoking another widget, such as a 
button or menu. For example, the user might select a font name from the 
listbox in Figure 18.12 and then click on a button widget to apply that font to 
some object; the Tcl script associated with the button can read out the 
selected listbox entry. 

It’s also common for a double-click on a listbox entry to invoke an 
operation on the selected entry. For example, the script for Figure 18.12 
creates a binding for double-clicks that sets the font of the listbox from the 
selected font family using the get widget command. The script fills the 
listbox by scanning through the list of font family names, sorted 
alphabetically, and entering them by storing the list in the listbox’s 
associated list variable. A user can click on an entry like “Courier” to select 
it. A double-click causes the listbox’s font to change to the selected font. 


18.9 Scrollbars 


Scrollbars control the views in other widgets. Each scrollbar widget is 
associated with some other widget such as a listbox or entry. For example, 
Figure 18.13 shows a scrollbar next to a listbox that displays the names of 
all the files in a directory. The scrollbar displays arrows, usually at each 
end, and a rectangular s/ider in a trough in the middle. The size and 
position of the slider indicate which of the listbox’s entries are currently 
visible in its window. In Figure 18.13 the slider covers the bottom 20% of 
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the area of the trough; this means that the listbox is currently displaying the 
last 20% of its entries. The user can adjust the view by clicking mouse 
button 1 on the arrows, which moves the view a small amount in the 
direction of the arrow, or by clicking in the trough on either side of the 
slider, which moves the view by one full screen in that direction. The view 
can also be changed by pressing on the slider and dragging it. The listbox 
displays the file names in a directory, and the scrollbar is used to change the 
view in the listbox. 


Figure 18.13 A scrollbar and a listbox working together 
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18.9.1 Scrolling a Single Widget 


The scrollbar uses its -commana option to notify the listbox when the user 
invokes scrolling operations, and the listbox uses its -yscro11commana option to 
notify the scrollbar when it changes its view. For example, Figure 18.13 
shows a listbox with a scrollbar, the script for which is as follows: 


listbox .files -relief raised -borderwidth 2 \ 
-yscrollcommand ".scroll set" \ 
-listvariable files 

scrollbar .scroll -command ".files yview" 

grid .files -row 0 -column 0 -sticky nsew 

grid .scroll -row 0 -column 1 -sticky ns 

grid rowconfigure . 0 -weight 1 

grid columnconfigure . 0 -weight 1 

set files [lsort -dictionary \ 
[glob -directory $tk_library/demos -tails *]] 


A scrollbar interacts with its associated widget using Tcl scripts. For 
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example, consider the script for Figure 18.13. The listbox is configured 
with a -yscrolicommana Option whose value 1S .scroi1 set. Whenever the view in 
the listbox changes, the listbox appends two numbers to the -yscroticommana 
value to generate a command such as 


scroll set 0.80 1.0 


The numbers give the percentage of the whole represented by the slider. The 
first fraction indicates the first information in the document that is visible in 
the window, and the second fraction indicates the information just after the 
last portion that is visible. The preceding command corresponds to the view 
in Figure 18.13. Then the listbox evaluates the command. In this case the 
command happens to be the widget command for the scrollbar, and it 
invokes the set action, which expects two arguments in just the form 
provided by the listbox. The set widget command causes the scrollbar to 
redraw its slider to correspond to the information in the arguments. 

When the user clicks on the scrollbar to change the view in the listbox, the 
scrollbar uses its -commana option to notify the listbox. For example, suppose 
that the user clicks on the up arrow in Figure 18.13. The scrollbar generates 
a Tcl command by appending scroii -1 unit to the value of its -commana option: 


.files yview scroll -1 unit 


Then the scrollbar evaluates the command. The widget command for the 
listbox has an action that takes exactly this form, and it causes the listbox to 
adjust its view so that the entry prior to the current top entry is displayed on 
the top line. After adjusting its view, the listbox invokes its -yscro11commana 
option to notify the scrollbar of the new view, and the scrollbar then 
redraws its slider. It is up to each widget to define what constitutes a “unit”; 
in this case, the listbox defines a unit as one entry. When the slider is 
moved, a different command is generated. In this case the command directs 
the widget to move to a new fraction offset; for example: 


.files yview moveto 0.73 


Here, the widget is directed to scroll so that the information at the top of the 
display is 73% from the beginning of the document. 

This same approach works for all widgets that support scrolling, and it 
could support different implementations of scrollbars, too. All that a widget 
must do to be scrollable is to provide a yview action for its widget command 
and a -yscrolicommana option. Scrollbars are not hard-wired to work with any 
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particular widget or widget class. Instead, the information is provided by 
setting the scrollbar’s -commana option. Likewise, it is possible to build new 
kinds of scrollbar widgets and have them work with any of the existing 
widgets as long as they provide a -commana option and a set action for their 
widget commands. 

Tk supports horizontal scrolling as well as vertical scrolling. Scrollbars 
have a vertical orientation by default, but they can be oriented horizontally 
by specifying the option -orient horizontal. Listboxes have a separate - 
xscrollcommand Option and an xview action for their widget commands to support 
horizontal scrolling. 


18.9.2 Synchronized Scrolling of Multiple Widgets 


It is not necessary to connect the scrollbar and widget directly. A procedure 
can be used in between to do things like scrolling multiple widgets with a 
single scrollbar. The trick to getting accurate synchronized scrolling is to 
identify a master widget that will control the scrollbar and the slave 
widgets. The accuracy comes into play when there are slight rounding errors 
in the floating-point calculations performed by each widget. When these 
calculations are forced to one widget, the rest stay in sync. In addition, a 
number of Tk extensions provide for multicolumn scrolling widgets to deal 
with the same problem. 

The following script creates what appears to the user as a two-column 
scrolled list, as shown in Figure 18.14: 
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# called by the listbox 
proc Yset {widgets master sb args} { 
if {$master eq "master"} { 
# Only the master sets the scrollbar 
$sb set {expand}$args 
set wl [lrange $widgets 1 end] 
} else { 
set wl [lrange $widgets 0 0) 
} 


Yview $wl moveto [lindex Sargs 0] 
} 
# called by the scrollbar 
proc yview {widgets args} { 

foreach w $widgets { 

$w yview {expand}$Sargs 

} 

} 


set widgets [list .1bl .1b2] 
-lb1 configure \ 
-yscrollcommand [list yset $widgets master .sb] 


.1b2 configure \ 
-yscrollcommand [list yset $widgets slave .sb] 
.sb configure -command [list yview $widgets] 


Figure 18.14 Scrolling multiple widgets together 


18.10 Scales 


A scale widget has an appearance similar to that of a scrollbar, but instead 
of scrolling another widget, it is used to select a numerical value by moving 
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the slider along the trough. You specify the minimum and maximum values 
for the scale with its -srom and -to options. Moving the slider changes the 
value in increments specified by -resolution, Which defaults to 1. The -orient 
option determines whether the scale is vertical OF horizontal, and you can 
control the size of the scale with the -iengtn option to specify the long 
dimension and the -wiatnh option to specify the narrow dimension of the 
trough, both of which accept any screen distance. By default, the scale 
displays its current value, but you can disable that by setting -showvaiue to 
false. You can display an optional text label by providing a string value to 
the -iabe1 option. You can also request the display of numerical tick marks 
by providing the numerical interval to the -tickintervai option. 

You can use the -variabie option to link the scale to a global or fully qualified 
namespace variable so that the value of the scale and the value of the 
variable are automatically synchronized. You can also retrieve the value of 
the scale with the get subcommand or set it with the se: subcommand. The 
scale also supports a -commana option, which lets you register a command to 
execute whenever the value changes; the scale automatically appends the 
updated value of the scale as an argument to the command before invoking 
it. 

The following script creates three horizontal scale widgets, each allowing 
integer values ranging from 0 to 5. Each scale has a descriptive text label 
and tick marks, but the value is not displayed. Any time a scale changes its 
value, it calls the upaatescore procedure to update the average value of the 
scales, which is displayed through a label widget. Figure 18.15 shows the 
result of running the script. 
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set score "Average score: 0.0" 
set food 0 

set ambiance 0 

set service 0 


# Calculate an average of the ratings to display 

proc updateScore {val} { 
global food ambiance service score 
set average [expr {($food + $ambiance + $service) / 3.0}] 
set score [format {Average score: %3.1f} $average] 


} 


scale .food -label "Food" -variable food \ 
-length 5c -width .25c -from 0 -to 5 \ 
-resolution 1 -tickinterval 1 -showvalue 0 \ 
-orient horizontal -command {updateScore} 

scale .ambiance -label "Ambiance" -variable ambiance \ 
-length 5c -width .25c -from 0 -to 5 \ 
-resolution 1 -tickinterval 1 -showvalue 0 \ 
-orient horizontal -command {updateScore} 

scale .service -label "Service" -variable service \ 
-length S5¢ -width .25¢ -from 0 -to 5 \ 
-resolution 1 -tickinterval 1 -showvalue 0 \ 
-orient horizontal -command {updateScore} 

label .score -textvariable score 


grid .food -padx 2 -pady 2 -sticky w 
grid .ambiance -padx 2 -pady 2 -sticky w 
grid .service -padx 2 -pady 2 -sticky w 
grid .score -padx 2 -pady 2 -sticky w 


Figure 18.15 Examples of scale widgets 


Average score: 3.3 
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18.11 Entries 


An entry is a widget that allows the user to type in and edit a one-line text 
string. Tk provides two different kinds of entry widgets: entry and spinbox. 
The spinbox combines an entry with up/down buttons. 


18.11.1 Entry Widget 


Figure 18.16 shows an entry widget that might be used for entering a file 
name. To enter text into an entry widget, the user clicks mouse button | in 
the entry. This makes a blinking vertical bar appear, called the insertion 
cursor. The user can then type characters, which are inserted at the point of 
the insertion cursor. The insertion cursor can be moved by clicking 
anywhere in the entry’s text. Text in an entry can be selected by pressing and 
dragging with mouse button 1, and it can be edited with a variety of 
keyboard actions, such as Delete or Backspace to delete the character just 
before the insertion cursor; see the reference documentation for details. The 
widget command for entries provides actions such as insert for inserting 
text, aeicte for deleting text, icursor for positioning the insertion cursor, and 
index for finding the character displayed at a particular position in the 
window. 


Figure 18.16 An entry widget with an identifying label 
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Here is the script for the widget shown in Figure 18.16: 


label .label -text "File name:" 

entry .entry -width 20 -relief sunken -bd 2 \ 
-textvariable name 

grid .label .entry -padx 1m -pady 2m 


The code specifies a -wiath option for the entry, which indicates how wide 
the window should be in characters. If the text becomes too long to fit in this 
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amount of space, only a portion of it is displayed; the view can be adjusted 
with an associated scrollbar widget, the arrow keys, the Home key, or the 
End key. The script for Figure 18.16 also specifies a -textvariabie option, 
which ties the text in the entry to the contents of the global variable name. 
Whenever the text in the entry is modified, name is updated and vice versa. 


18.11.2 Spinbox 


A spinbox provides all the features of an entry widget plus a pair of 
up/down buttons. Pressing one of the buttons moves or spins through a fixed 
set of ascending or descending values such as times, dates, or integers. The 
value may be edited directly as in an entry widget unless the readoniy state is 
set. To spin through a list of months, for example, the -vaiues option 1s used, 
as shown in Figure 18.17. In this example the entry box is not editable: 


set months {January February 
March April May June July 
August September October 
November December} 
label .label -text "Month:" 
spinbox .spin -width 2 \ 
-relief sunken -bd 2 \ 
-textvariable month \ 
-state readonly \ 
-values $months 
grid .label .spin -padx 1m \ 
-pady 2m 


Figure 18.17 A spinbox allowing selections from a list of values 
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A spinbox also can be set to spin through a range of numerical values with 
the -from, -to, and -increment Options. Figure 18.18 shows an example of a 
spinbox that can spin through integer values from 6 to 72 in increments of 2. 
Because the -state 1S Set tO norma, the font size also may be set by typing ina 
number directly: 
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Figure 18.18 A spinbox that spins through a range of integer values 
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Font size: [122 


label .label -text "Font size:" 
spinbox .spin -width 2 \ 
-relief sunken -bd 2 \ 
-textvariable size \ 
-from 6 -to 72 \ 
-increment 2 \ 
-state normal 
grid .label .spin -padx 1m \ 
-pady 2m 


18.11.3 The snow Option 


The -show option on an entry widget causes the entry to hide the typed-in 
characters by displaying the -snow character instead. This is useful for 
accepting secret information such as passwords without displaying them on 
the screen. Figure 18.19 demonstrates an entry with the -snow option created 


with the following code: 


label .label -text Password: 
entry .passwd -show # 
grid .label .passwd -sticky ew 


Figure 18.19 Example entry widget with the -snow option used to hide the 
contents 
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18.11.4 Validation 


Entry widgets also provide for entry validation through a supplied script. 
Using the -va1iaate option, you can specify that the widget perform validation 
per keystroke, on a change in focus, or both. Validation is done by a script 
specified with the -vaiidationcommana option. The script must return a Boolean 
value indicating whether the change is valid and accepted or invalid and 
rejected. You can also specify an -invalidcommana option that provides a script 
to execute when the validation script returns 0; a typical use is to invoke 
pe1l, Which rings the display’s bell. 


Note 


An uncaught error during the evaluation of the validation script 
disables further validation on the entry by automatically setting - 


validate tO none. 


The example in Figure 18.20 validates the entry to allow legal decimal 
integer or floating-point values. Notice in the code for this example that the 
-validatecommana Option has an argument that begins with s. Such arguments are 
substituted with appropriate values before evaluation by the entry widget. In 
the case of an entry widget, <w is replaced with the name of the widget, +r 
with the value of the entry if the edit is allowed, and ¢s with the text string 
being inserted or deleted. This is a convenient way to pass information to 
the command about the state of the widget. There are several places 
throughout Tk where percent substitutions are performed. See the entry 
reference documentation for a complete list of percent substitutions that are 
supported for validation. 


Figure 18.20 Entry validation 
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This example script validates the entry by using the Tcl string is command to 
check if the value can be represented as a double-precision-floating point 
value. But because the script is called for each keystroke, it must also 
accept some intermediate strings as valid as well, such as if the user has 
entered an optional sign character but not yet entered any digits. It does this 
by calling regexp if the string is command returns o. Note that string is returns 
1 1f its value is an empty string, so this also allows a user to delete all of the 
characters from the entry. The script also “echoes” the value entered in a 
label beneath the entry: 


label .label -text "Enter value:" 

entry .value -width 15 -validate all \ 
-validatecommand { CheckValue ¢P } 

label .echo -textvariable echo 

grid .label .value -padx im -pady 2m 

grid .echo - -padx lm -pady 2m 


proc CheckValue { newValue } { 


global echo 
if { [string is double $newValue] 


| [regexp -- {*[+-]?\.?$} $newValue] } 
set echo SnewValue 
return 1 
f 
} else { 
return 0 
Note 


Validating an entry is very complicated since the value in the entry box 
is “invalid” most of the time. These invalid intermediate points must be 
allowed or else you will never get to a valid entry. For this reason, 
validating on keystrokes is rarely useful. This example illustrates both 
the capability of the entry box to perform validation and the complexity 
of doing so. 


18.12 Menus 
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Tk’s menu widget is a building block that can be used to implement several 
varieties of menus, such as pull-down menus, cascading menus, and pop-up 
menus. A menu is a toplevel widget that contains a collection of entries 
arranged in a column, as shown in Figure 18.21. Menu entries are not 
distinct widgets, but they behave much like buttons, checkbuttons, and 
radiobuttons. The following types of entries may be used in menus: 


*® command 


Similar to a button widget. Displays a string or image and invokes a Tcl 
script when mouse button | is released over it. 

® checkbutton 
Similar to a checkbutton widget. Displays a string or bitmap and toggles a 
variable between o and i when button 1 is released over the entry. Also 
displays a check mark selector like a checkbutton widget. 

® radiobutton 
Similar to a radiobutton widget. Displays a string or image and sets a 
variable to a particular associated value when button | is released over it. 
Also displays a radio selector in the same way as a radiobutton widget. 

* cascade 
Similar to a menubutton widget. Posts a cascaded submenu when the mouse 
passes over it. See below for more details. 

® separator 


Displays a horizontal line for decoration. Does not respond to the mouse. 


Figure 18.21 A menu 
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Menu entries are created with the aaa widget command for the menu, and 
they have configuration options that are similar to those for buttons, 
checkbuttons, and radiobuttons. 
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Menus appear on the screen only for brief periods of time. They spend most 
of their time in an invisible state called unposted. For a menu to be invoked, 
it must first be posted. This is done with the post action for its widget 
command; for example, the menu in Figure 18.21 could be posted with the 
command .m post 100 100. Once a menu is posted the user can move the 
pointer over one of the menu’s entries and release button | to invoke the 
entry. After the menu has been invoked, it is usually unposted until it is 
needed again. 

The following script creates a menu. The aca action for the menu’s widget 
command is invoked to create the individual entries in the menu. 


option add *Menu.tearOff 0 
menu .m 
.m add checkbutton -label Bold -variable bold 
.m add checkbutton -label Italic -variable italic 
.m add checkbutton -label Underline -variable underline 
.m add separator 
.m add radiobutton -label Times -variable font \ 
-value Times 
.m add radiobutton -label Helvetica -variable font \ 
-value Helvetica 
add radiobutton -label Courier -variable font \ 
-value Courier 
.m add separator 
add command -label "Insert Bullet" \ 
-command "insertBullet" 


3 


4 


= 
= 


add command -label "Margins and Tabs..." \ 

-command "mkMarginPanel" 
Menus can be posted and unposted in various ways to achieve different 
effects. The next sections describe pull-down menus and cascaded menus, 
where posting and unposting are handled automatically. Other approaches 
such as pop-up menus and option menus are also possible. 


Note 


Tk menus support a “tear-off’ feature. If enabled, a special separator 
appears as the first option; if selected, the menu is displayed as a 
separate toplevel window. Tear-off menus were a typical feature of 
Motif interfaces, and so they are enabled on Tk menus by default. Tear- 
offs are rarely found in modern interfaces, though, so typically you'll 
want to disable the tear-off feature by default. This is accomplished by 
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including the command option add *Menu.tearort o to your script before 
creating any menu widgets. This works by setting a value that applies 
to all menus in the option database, described in Chapter 28. 


18.12.1 Pull-Down Menus 


Menus are most commonly used in a pull-down style. In this style the 
application displays a menu bar near the top of its main window, as shown 
in Figure 18.22. A menu bar is drawn at the top of the window and contains 
several entries that act like buttons, each of which is associated with a 
menu. (On Mac OS X, the menu bar appears at the top of the screen.) When 
a user presses mouse button | over a menu entry, the associated menu is 
posted underneath the entry (for example, the Edit menu is posted in Figure 
18.22). Then the user slides the pointer down over the menu, with the mouse 
button still pressed, and releases the mouse button over the desired entry. 
When the button is released, the menu entry is invoked and the menu is 
unposted. The user can release the mouse button outside the menu to unpost 
it without invoking an entry. 


Figure 18.22 An example of pull-down menus with one menu posted 
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The following script creates a menu bar. The menu bar frame (.moar) has six 
children, each of which is a cascaded menu with an associated menu. The 
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definition of the menus 1s incomplete: only part of the definition for a single 
menu is shown. 


option add *Menu.tearOff 0 
menu .mbar 
configure -menu .mbar 


.mbar add cascade -label File -menu .mbar.file -underline 0 

.mbar add cascade -label Edit -menu .mbar.edit -underline 0 

.mbar add cascade -label View -menu .mbar.view -underline 0 

.mbar add cascade -label Graphics -menu .mbar.graphics ‘ 
-underline 0 

.mbar add cascade -label Text -menu .mbar.text -underline 0 

.mbar add cascade -label Help -menu .mbar.help -underline 0 


menu .mbar.text 


.mbar.text add checkbutton -label Bold -variable bold \ 
-underline 0 

-mbar.text add checkbutton -label Italic -variable italic \ 
-underline 0 


If the user presses button 1 over a menu entry and then moves the pointer 
over another menu entry, the old entry unposts its menu and the new entry 
posts its menu. This allows the user to scan all of the menus by sliding the 
pointer across the menu bar. 

If the user releases the mouse button over an entry, the menu stays posted 
and the user is not able to do anything else with the application until the 
menu is unposted, which the user does by invoking one of its entries, or 
clicking outside the menu without invoking any entry. Situations like this 
where a user must respond to a particular part of an application and cannot 
do anything with the rest of the application until responding are called 
modal user interface elements. Menus and dialog boxes are examples of 
modal interface elements, which are implemented using the grab mechanism 
described in Chapter 27. 

In Tk, menu bars are an integral part of a toplevel window. The toplevel 
manages the menu bar placement differently for different platform 
environments. A menu bar is created by building a menu and then giving it to 
the toplevel for display by configuring the -menu option on the toplevel 
window. In the script for Figure 18.22, the -menu and -underline Options are 
specified for each entry in addition to its label string. The -menu option 
identifies the menu associated with the entry. The -unaer1ine option gives the 
index of a character to underline when displaying the label in the entry. This 
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character is used for keyboard traversal, as described in Section 18.12.3. 


18.12.2 Cascaded Menus 


A cascaded menu is a menu that is subservient to another menu. It is 
associated with a cascade menu entry in its parent menu. Note that the menu 
bar is simply a list of cascaded menus. When the pointer passes over a 
cascade entry in a menu, the associated menu 1s posted just to the right of the 
cascade entry, as shown in Figure 18.23. The user can then slide the pointer 
to the right onto the cascaded menu and invoke an entry in it. After an entry 
has been invoked in a cascaded menu, both it and its parent are unposted. 
All that is needed to create a cascaded menu is to define the cascaded menu 
and create a cascade entry in its parent, using the -menu option in the cascade 
entry to specify the name of the cascaded menu. Menus can be cascaded to 
any depth, but for best usability it 1s a good rule of thumb to keep the 
maximum depth to three. 


Figure 18.23 A cascaded menu 
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The following example shows the changes to the script for Figure 18.22 that 
are needed to create a cascaded menu: 
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menu .mbar.graphics 


.mbar.graphics add cascade -label "Line Color" \ 


-ménu .mbar.graphics.color -underline 5 
.mbar.graphics add cascade -label "Line Width" \ 

-menu .mbar.graphics.width -underline 5 
.mbar.graphics.width add radiobutton -label "0.25 point" \ 


-variable lineWidth -value 0.25 


18.12.3 Keyboard Traversal and Shortcuts 


Pull-down menus can be posted and invoked without the mouse using a 
technique called keyboard traversal. One of the letters in each menu entry is 
selected as the traversal character for that entry with the -underiine option; it 
is underlined in the entry’s window. If that letter is typed while the Alt key 
is held down, the entry’s menu is posted. Or the user can press the F10 key 
to post the leftmost menu in the menu bar. Once a menu has been posted, the 
arrow keys can be used to move among the menus and their entries. The left 
and right arrow keys move left or right among the toplevel entries, unposting 
the menu for the previous entry and posting the menu for the new one. The 
up and down arrow keys move among the entries in a menu, activating the 
next higher or lower entry. You can press the Return key to invoke the active 
menu entry, or Escape to abort the menu traversal without invoking anything. 
Traversal characters can also be defined for individual menu entries with 
the -underline Option, as shown in the code for Figure 18.22. The traversal 
character is underlined when the menu entry is displayed, and if it or its 
lowercase equivalent is typed at a time when the menu is posted, the entry is 
invoked. 

In many cases it is possible to invoke the function of a menu entry without 
even posting the menu by typing keyboard shortcuts. If there is a shortcut 
for a menu entry, the keystroke for the shortcut is displayed at the right side 
of the menu entry (for example, you might want to display ctri+z as the 
shortcut for an Undo menu entry). This key combination may be typed in the 
application to invoke the same function as the menu entry (for example, type 
z while holding the Control key down to invoke the Undo operation without 
going through the menu). The -acce1erator option for a menu entry specifies a 
string to display at the right side of the entry. Common modifiers, which may 
be combined, include controi, ctrl, shift, Command, Cmd, Option, and opt. 
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Note 


On Mac OS X, these modifiers are mapped automatically to the 
corresponding modifier icons that appear 1n menus. 


A key binding must also be defined in order for the shortcut to work. This is 
done using the bina command like so: 


bind . <Control-Key-z> {.mbar.edit invoke "Undo"} 


When the keyboard event is bound to ., the toplevel window, the event is 
caught no matter which internal window has the keyboard focus. More 
information about the bina command and event propagation can be found in 


Chapter 22. 


18.12.4 Platform-Specific Menus 


Each platform has one or more menus for which Tk provides special 
handling. To take advantage of this feature, you must give particular names 
to the menu widgets you create in support of these special menus. In all 
cases, these menu widgets must be created with the name of the menu bar 
menu concatenated with the special name (that is, .menuzar. special for your 
application’s main window, OF .topievel.menuBar.special for a secondary 
toplevel). 

On X11 windowing systems, the Help menu should always appear at the far 
right of the window. Tk does this automatically as long as you use .neip as 
the last component of the name of the menu widget implementing the Help 
menu (for example, .mbar.neip for your application’s main window, or 
.docl.mbar.help for a secondary toplevel). 

On Windows systems, you can access the system menu for a window, which 
is the menu posted by clicking on the application’s icon in the window title 
bar. Any entries you add appear after the standard Windows entries. To 
access the system menu, use .system aS the last component of the menu’s name 
(for example, .mbar.system). 

On Mac OS X, you can append entries to the standard Help menu by 
creating a menu widget whose name ends in -neip (for example, .mbar.neip). 
Mac OS X also has what’s known as an application menu, which is the 
second menu in the menu bar, the title of which is the same as your 
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application name. To access the application menu, create a menu whose 
name ends in .appie (for example, .mbar.appic). Any entries that you add to the 
.apple Menu appear before the system-standard entries. 


Note 


The .appie menu really does access the application menu (second from 
the left), not the leftmost menu with the apple icon. The name is a 
holdover from pre—OS X days when application-specific entries really 
did go under the apple (icon) menu. 


The Mac OS X application menu also provides a standard “Preferences” 
item. This item is disabled unless you define a procedure named ::tx::mac:: 
ShowPreferences. Typically, you would define this procedure to display any 
preferences dialog that you might have implemented. 


18.12.5 Pop-up Menus 


The tx popup utility is a convenience procedure that makes it easy to post 
pop-up menus. Pop-up menus are typically bound to mouse button 3 on 
Windows and Unix systems, corresponding to the right mouse button. On 
Mac OS X, they should typically respond to a click of the left (or only) 
button while the Control key is held, or the right button on a multibutton 
mouse, which maps to mouse button 2. Therefore, in a platform-independent 
application, you should use the tx windowingsystem Command to determine if 
your application is running on the native Mac OS X windowing system, 
which is indicated by a return value of aqua. 

Pop-up menus also are typically sensitive to the location of the mouse 
pointer at the time the button is pressed. This means that the menu that 
appears has actions related to the item under the mouse pointer. The tx popup 
utility makes it easy to bind the mouse button to a menu: 


if {[tk windowingsystem] =="aqua"} { 

bind .lbox <ButtonPress-2> {tk popup .menu %X %Y} 

bind .lbox <Control-ButtonPress-1> {tk_popup .menu &X %yY} 
} else { 

bind .lbox <ButtonPress-3> {tk popup .popup menu %X £&Y} 


When the appropriate mouse button is pressed over the .150x widget, the «x 
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and :y arguments are replaced with the x- and y-coordinates of the mouse 
pointer. In this example, the tx popup utility posts .popup menu at the appropriate 
location relative to the mouse pointer location, usually immediately below 
and to the right of the pointer. The bina command 1s discussed in more detail 


in Chapter 22. 


Note 


The platform dependency of the bindings could also be handled through 
the definition of virtual events, which are also described in Chapter 
22. 


18.13 Panedwindow 


Several commonly used applications, like e-mail clients and file browsers, 
have a window layout similar to that shown in Figure 18.24. The main 
window is divided into two or more panes with a movable divider between 
them. This is handled in Tk with the panedwindow widget. Panes can be 
arranged either horizontally or vertically, depending on whether you set the 
panedwindow’s -orient Option tO horizontal OF vertical, respectively. You can 
set the -shownanaie option to a Boolean value to specify whether or not you 
want to display a resize handle on each sash separating panes. 


Figure 18.24 The panedwindow manages a list of widgets into a horizontal 
row or vertical column. 
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Each pane is a cell that contains another widget. Typically, you arrange the 
contents of each pane into a frame widget, then add each frame to the 
panedwindow using the aaa subcommand. (Chapter 21 explains how to 
arrange widgets within a frame.) In Figure 18.24 the left pane contains a 
listbox showing a list of files, and the right pane contains a text widget to 
display the contents of the selected file. 

The following script shows how to add existing widgets to a panedwindow: 


# The .left frame contains a listbox and scrollbar 
# The .right frame, a text widget and scrollbars 
# These are placed in a panedwindow: 


panedwindow .pw -orient horizontal 
-_pw add .left .right 


Each pane that you add is controlled by a set of options. You can set the 
option values when you add the pane with aaa, or afterward with the 
paneconfigure SUbcommand. You can query the value of a pane option with the 
panecget SUbCOmmand; for example: 


-pw panecget .left -sticky 
=> nesw 
-_pw paneconfigure .left -minsize 2i 


The following pane options are supported: 
© -after widget 


Inserts the widget after the wiagee specified, which should be the name of a 
widget already managed by the panedwindow. 
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® -before widget 
Inserts the widget before the wiagee specified, which should be the name of a 
widget already managed by the panedwindow. 

® -height size 
Specifies a height for the widget, expressed as a screen distance. If size 1s 
an empty string, or if -neignt 18 not specified, the height requested internally 
by the widget is used initially; the height may later be adjusted by the 
movement of sashes in the panedwindow. 

® -hide boolean 
Controls the visibility of a pane. When pooiean 18 true, the pane is not visible, 
but it is still maintained in the list of panes. 
Specifies that the size of the pane cannot be made less than size, expressed 
as a screen distance. 

® -padx size 
Specifies horizontal padding added around the widget, expressed as a 
screen distance. 

® -pady size 
Specifies vertical padding added around the widget, expressed as a screen 
distance. 

© -sticky style 
Controls the position and stretching of a widget if a widget’s pane is larger 
than its requested dimensions. styie 1s a string that contains zero or more of 
the characters n, s, ¢, or w. Each letter refers to a side (north, south, east, or 
west) to which the widget “sticks.” If both n and s (or ¢ and w) are specified, 
the window is stretched to fill the entire height (or width) of its pane. 


® -stretch when 


Controls how extra space is allocated to each of the panes. You can set the 
pane tO always OF never Stretch. Alternatively, you can specify that the pane 
stretch only if itis the first, 1ast, OF middle pane. 

* -width size 
Specifies a width for the window, expressed as a screen distance. If size 1s 
an empty string, or if -wiatn is not specified, the width requested internally 
by the window is used initially; the width may later be adjusted by the 
movement of sashes in the panedwindow. 
Widgets previously added to a panedwindow can be removed from it using 
the forget subcommand. You can also retrieve a list of widgets managed by 
the panedwindow using the panes subcommand; the widgets are returned in 
the order in which they are displayed: 
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.pw panes 
= left .right 


Note 


The panedwindow is both a widget and a geometry manager. Geometry 
management is discussed at length in Chapter 21. 


18.14 Standard Dialogs 


Tk provides a set of utility procedures and dialogs. Three are described 
here, but refer to the documentation for a complete list. You can also create 
your own custom dialogs, a topic that is discussed in Chapter 27. 

At times in an application it is necessary to report a condition or ask a 
question that needs immediate attention. This can be handled easily in Tk 
using the tx _messagesox dialog. Calling this procedure presents a dialog box 
containing a message and a set of buttons, depending on the -type specified. 
An image is displayed next to the message text as defined by the -icon 
option. This image is used to help the user identify the importance of the 
message, so the possible values are error, info, question, aNd warning. The 
image varies from one platform environment to another, and it is typically 
standardized across all applications for that environment. Figure 18.25 
demonstrates a simple yesno message box. The -parent option specifies an 
application widget that the tx messagenox uSeS for positioning the dialog. The 
dialog box is centered over the top of the parent widget. The message box 
dialog is modal and blocks further execution of the Tcl application until the 
user responds by pressing one of the buttons. The return value is a string 
indicating which button was pressed, such as yes OF no. 


Figure 18.25 Example of Tk’s built-in messageBox dialog 
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The following script shows a message box and the response. The function 
returns a value based on which button the user presses. 


tk messageBox -type yesno -icon question \ 
-message "Do you like coffee?" -parent . 
=> yes 


Selecting operating system files for open and save operations is a common 
enough task that each platform environment has a standardized way of 
presenting a dialog for file selection. These dialogs are common across all 
applications, reducing the learning curve for users. Tk provides access to 
these common dialogs with the tx getopenFile, tk getSaverile, and 
tk chooseDirectory procedures. When these procedures are called, the Tk 
application waits until the user completes the file selection. The procedure 
then returns the selected file or files (or an empty string if the user selected 
no files), and the Tcl script continues. In the code for Figure 18.26, the - 
initialfile Option is used to seed the dialog so that it displays the given file 
name. The -iiter can be used to limit the files visible to those that make 
sense for the application at hand. 


Figure 18.26 Invoking the native file navigator dialog boxes 
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The following command creates a file dialog to open an existing file. The 
file selected is returned by the call, or an empty string if the dialog box is 
canceled. A variety of initial conditions (-initiaifiie shown here) and filters 
can be configured via options to these calls: 


tk_getOpenFile -initialfile messagebox.tcl 
-filetypes {{Tcl tcl} {All *}} 


18.15 Other Common Options 


The widget descriptions discussed in this chapter introduced most of the 
common kinds of options, such as colors and fonts. This section describes a 
few other options that are supported by many widgets. 


18.15.1 Widget State 


Interactive widgets and menu entries have a -state option associated with 
them. The default value of -state 1S norma1, in which case the default widget 
class bindings make the widget responsive to user interaction. For example, 
a button responds to a mouse click by invoking its -commana script, a listbox 
lets a user scroll through and select its items, an entry widget allows a user 
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to edit its text, and so forth. Setting the -state option to aisabiea causes the 
default widget class bindings to make the widgets unresponsive to user 
input; most widgets also change their visual appearance, for example, 
appearing “grayed out.” Several interactive widgets also support a value of 
active, Which is used primarily by the default class bindings to highlight the 
widget when the mouse pointer is over the widget. 

The most common use of the -state option in an application is to disable 
features of an application under certain circumstances and enable them in 
others. For example, you might enable a Copy button (set its -state to norma1) 
if the user has selected some text in your application and disable it (set its - 
state tO disablea) Otherwise. 

Other widgets have some additional states, such as readoniy for an entry or 
spinbox and hidden for a canvas; see the appropriate sections of this book 
and the reference documentation for more information about these states. 


18.15.2 Widget Size Options 


Many widgets support a -wiatn option, and some support a -neight option, to 
specify a preferred minimum size. If a widget contains text, these values are 
usually interpreted in terms of the number of characters wide and the 
number of lines tall, so the actual size depends on the font and size of the 
text. If a widget contains an image or bitmap, the values are usually 
interpreted as pixels. If a widget is not large enough to display all of its 
contents, it usually clips the contents subject to the -anchor option discussed 
in the next section. 

Although you can try to calculate or forecast sizes for your widgets, it’s 
usually easiest with widgets such as labels and buttons to leave these 
options with their default value, which is o. In this case, the widgets 
automatically size themselves to be just large enough to accommodate their 
contents. And in other cases, such as entries or text widgets, you often use 
the geometry managers to resize the widgets based on the user resizing the 
window, which overrides any values set for -neignt and -wiatn. 


18.15.3 Anchor Options 


An anchor position indicates how to attach one object to another. For 
example, if the window for a button widget is larger than is needed for the 
widget’s text, an anchor option may be specified to indicate where the text 
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should be positioned in the window. Anchor positions are also used for 
other purposes, such as telling a canvas widget where to position a bitmap 
relative to a point associated with the item, or telling the packer geometry 
manager where to position a window in its frame. 
Anchor positions are specified using one of the following points of the 
compass: 

* »—center of the object’s top side 

* ne—top right corner of the object 

¢ -—center of the object’s right side 

* se—lower right corner of the object 

¢ -—center of the object’s bottom side 

* sw—lower left corner of the object 

* .—center of the object’s left side 

* nw—top left corner of the object 

* center—center of the object 
The anchor position specifies the point on the object by which it is to be 
attached, as if a pushpin were stuck through it at that point, pinning the 
object someplace. For example, an -anchor option of » specified for a button 
means that the button’s text or bitmap is to be attached by the center of its 
left side, and that point is positioned over the corresponding point in the 
window. Thus, » means that the text or bitmap is centered vertically and 
aligned with the left edge of the window. For bitmap items in canvas 
widgets, the -anchor option indicates where the bitmap should be positioned 
relative to a point associated with the item; in this case, w means that the 
center of the bitmap’s left side should be positioned over the point, so that 
the bitmap actually lies to the east of the point. Figure 18.8 and Figure 18.9 
show the use of the -anchor option to cause the buttons to align on the left (for 
west) side of the window. 


18.15.4 Internal Padding 


Many widgets support -paax and -paay options, which control internal 
padding. The -paax option accepts a screen distance specifying the minimum 
amount of space horizontally between the widget’s borders and its content; 
the -paay option determines the minimum vertical spacing between the 
widget’s borders and its content. 


18.15.5 Cursor Options 
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Every widget class in Tk supports a -cursor option that determines the image 
to display for the pointer when it is over that widget. If the -cursor option 
isn’t specified or if its value is an empty string, the widget uses its parent’s 
cursor. Otherwise, the value of the cursor option must be a proper Tcl list 
with one of the following forms: 

* name fgColor bgColor 

° name fgColor 

*® @sourceFile maskFile fgColor bgColor 

*® @sourceFile fgColor 

* @sourceFile 
In the first three forms name refers to one of the predefined cursors. You can 
find a complete list of all the predefined names in the cursors reference 
documentation. 


If name 18 followed by two additional list elements, as in the command 


.f config -cursor {arrow red white} 


the second and third elements give the foreground and background colors to 
use for the cursor; as with all color values, they may have any of the forms 
described in Section 18.3. If only one color value 1s supplied, it gives the 
foreground color for the cursor and the background is transparent. If no 
color values are given, black is used for the foreground and white for the 
background. 

If the first character in the -cursor value 1s e, the image(s) for the cursor is 
taken from files in bitmap format rather than the X cursor font. If two file 
names and two colors are specified for the value, as in the following widget 
command, 


.f config -cursor \ 
{@cursors/bits cursors/mask red white} 


the first file is a bitmap that contains the cursor’s pattern (1s represent 
foreground and os background) and the second file 1s a mask bitmap. The 
cursor is transparent everywhere that the mask bitmap has a o value; it 
displays the foreground or background wherever the mask is :. If only one 
file name and one color are specified, the cursor has a transparent 
background. This feature is supported only on the X windowing system. 

The final form, which works on Windows systems only, loads a Windows 
system cursor (with either a .ani Or .cur extension) from the file specified by 
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sourceFile. 


On Windows and Macintosh systems, some cursors are mapped to native 
cursors. The look of these cursors depends on the user’s preferences. Some 
additional cursors are defined that are available only on a Windows or 
Macintosh platform. See the cursors reference documentation for a complete 
list. 
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19. Themed Widgets 


Themed widgets take a different approach from the classic Tk widget set. 
They separate, to the extent possible, the code implementing a widget’s 
behavior from the code implementing its appearance. While classic widgets 
are configured through the option database or by directly modifying options 
on each widget, the size, shape, color, fonts, and so on of themed widgets 
are controlled by their style. Themed widgets allow an application’s look 
and feel to be controlled by its environment (e.g., Windows user 
preferences) or by centralized application-defined styles. The resulting 
appearance is more consistent throughout the application, as well as with 
the native look and feel of the user’s windowing system. 


19.1 Comparing Classic and Themed Widgets 


The main advantage to using themed widgets is to give a native look to an 
application by selecting the theme that fits the user’s current desktop 
environment. Classic widgets on Microsoft Windows and Mac OS X try to 
emulate native widgets for buttons, scrollbars, checkbuttons, and 
radiobuttons, but these appearances can become dated with newer versions 
of the windowing system. This is especially apparent with X-based classic 
widgets, which are still based largely on the look of the Motif widget 
toolkit. Figure 19.1 illustrates the classic Tk checkbutton widget along with 
its themed variations for each platform. In some cases the difference may be 
subtle, but there are small changes that make a big difference, like the 
background blending on the Mac OS X checkbutton. 


Figure 19.1 Classic and themed checkbutton variations 
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Another benefit to themed widgets is that they are simpler to use than classic 
widgets. Themed widgets require much less configuration to give your 
application a consistent and attractive appearance, especially if you want 
subsets of widgets to have special appearances or behaviors. Customizing 
classic widgets throughout your application requires you to either set the 
configuration options for each widget individually or through the Tk option 
database (described in Chapter 28). For themed widgets, you can define a 
new style—usually by inheriting the definitions of an existing style— 
customize specific configuration options for the new style, and then assign 
the new style to individual widgets as needed. This process is covered in 
Section 19.9. 

Table 19.1 lists the classic widgets and how they compare to the themed 
widgets. Some of these widgets are the same as the basic Tk widget set, and 
others provide additional behaviors not found in the classic Tk widgets. 
Some classic widgets, such as the canvas and text classes, don’t have a 
themed equivalent, and the themed widgets include some new widget types, 
such as the combobox, notebook, aNd treeview Classes. 


Classic Tk 


Themed XP 


Themed Aqua 


Themed X11 (clam) 


Table 19.1 Classic Widget Classes and Their Corresponding Themed 
Widget Classes 
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Classic widget Themed widget 
button ttk: :button 
canvas 
checkbutton ttk::checkbutton 
ttk: :combobox 
entry ttk: :entry 
frame ttk::frame 
“label ttk::label 
labelframe ttk: :labelframe 
listbox 
menu 
menubutton ttk: :menubutton 
ttk: :notebook 
panedwindow ttk: :panedwindow 
ttk: :progressbar 
- radiobutton ttk::radiobutton 
scale ttk::scale 
scrollbar ttk::scrollbar 
ttk::separator 
ttk::sizegrip 
spinbox 
text 
toplevel 


ttk: :treeview 

Widgets that have both a classic Tk class and a themed widget class are 
functionally equivalent but not directly interchangeable. The themed widgets 
do not have options that control color, borders, and so on; instead, these 
aspects of the widget are controlled by the theme. Also, some themed 
widgets have different widget commands from their classic counterparts. 
Subsequent sections of this chapter focus on the new widget classes added 
by the themed widgets. 


Note 


If you decide to replace classic widgets in an existing Tk application 
with themed widgets to update the application’s appearance, you 
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should read the reference documentation carefully to identify the exact 
differences between the themed widgets and the classic widgets you 
are replacing. 


19.2 Combobox 


The ttk::combobox widget combines an entry widget with a drop-down 
listbox. This widget can be used like the spinbox to select from a fixed set 
of values, but it allows the direct selection of a value without incrementing 
through the list. Or it can be used to accumulate a history of values that have 
been entered directly into the entry box. Figure 19.2 shows a combobox 
used for performing searches. In this example, each time a new search string 
is typed in, the string is added to the list of values for the combobox. 
Pressing the down arrow to the right of the entry field displays a drop-down 
box showing the past search values. Selecting one of these values updates 
the entry with the new value. The following script creates the combobox 


shown in Figure 19.2: 


ttk::combobox .cb 

grid .cb 

proc UpdateCombo {w} 
set new [Sw get] 
set values [Sw cget -values] 
if {Snew ni $values} { 

set values [linsert S$values 0 Snew] 


r 
‘ 
t 


Sw configure -values $values 


\ 
j 


bind .cb <Return> {UpdateCombo %w} 


Figure 19.2 Example of a themed combobox widget 
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‘ combo |. ||| X| 
Iowa y 
Ohio 
Mississippi 
Texas 
Georga 
Washington 7 
California 

| 
Florida 
New York 


f combo (- \feyix) 
— 


19.3 Notebook 


The ttk::notebook widget provides a way to manage windows by dividing 
them into pages, tying each page to a user-selectable tab, and displaying 
only one page at a time. This widget is commonly used in complex dialog 
boxes, and there are other useful applications for it, such as the simple text 
editor shown in Figure 19.3. 


Figure 19.3 Example of a themed notebook widget 


Simple ttk Text Editor 
File 
[J cursors,tel|){ "] ttk_buttons. tel [J notebook. tel 


# 
# Notebook example 
# 


# Tcl and the Tk Toolkit, 2nd Edition 
# 


ttk::frame .f 
set nb [ttk::notebook .f.nb] 


pack $nb -fill both -expand 1 
pack .f -fill both -expand 1 


Minbar. file add command -label "Open..." -command “addFile $nb" 

-tnbar.file add command -label "Save" -command "'saveFile $nb" 

-Mnbar.file add command -label "Save As..."' -command "saveAs $nb" 

-tnbar.file add separator 

-Mnbar.file add command -label "Close Window" -command "closeWindow $nb" 
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A notebook is somewhat similar to a panedwindow in that it acts as a 
manager for other widgets. When a tab is selected (either programmatically 
or by a user clicking on it), the notebook displays a window, hiding any 
child window that was previously displayed. Typically, you arrange the 
contents of each pane into a ttk::frame or frame widget, then add each frame 
to the notebook using its aaa subcommand. (Chapter 21 explains how to 
arrange widgets within a frame.) 
Tabs are referenced by an identifier. There are several methods of 
specifying a tab identifier: 

¢ An integer index starting with o for the first tab 

¢ The name of the child widget managed by the notebook 

¢ A screen position of the form ex, y, where x and y are expressed as 

pixels relative to the upper-left corner of the notebook widget 

° The literal string current, which refers to the currently selected tab 
Each child window that you add is controlled by a set of options. You can 
set the option values when you add the window with aaa, or afterward with 
the tab subcommand, which accepts a tab identifier as its first argument: 


notebook tab tabid ?option? ?value option value ...? 


The following tab options are supported: 
* -compound style 
Specifies how to display the image relative to the text, when both -text and - 
image are present. See Section 19.10 for legal values. 
® -image image 
Specifies the name of an image object to display in the tab. 
® padding space 
Specifies the amount of extra space to add around the outside of the tab 
window, expressed as a screen distance. The padding is a list of up to four 
length specifications: tert, top, right, and bottom. If fewer than four elements 
are specified, bottom defaults to top, rignt defaults to iert, and top defaults to 
left. 


® -state state 


Indicates the state, which is either normal, disabled, OF hidden. If aisabiea, the tab 
is not selectable. If niaaen, the tab is not shown. 

© -sticky style 
Controls the position and stretching of a widget if a widget’s tab window is 
larger than its requested dimensions. styie 1s a string that contains zero or 
more of the characters n, s, ¢, or w. Each letter refers to a side (north, south, 


east, or west) to which the widget “sticks.” If both » and s (or « and w) are 
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specified, the window is stretched to fill the entire height (or width) of its 
window. 

© -text string 
Specifies a string to be displayed in the tab. 

® -underline index 
Specifies the integer index (zero-based) of a character to underline in the 
text string. The underlined character is used for mnemonic activation if 
ttk: notebook: :enableTraversal 18 Called. 


The insert widget command inserts a tab at a specified position: 


notebook insert position widget option? \ 
?value option value ...? 


The position can be a zero-indexed integer value, or the keyword ena to add 
the tab to the end. If the wiaget is already managed by the notebook, it is 
moved to the indicated position. 

You can hide a tab with the nice widget command, which is equivalent to 
setting the -state of that tab to niaden. On the other hand, the forget widget 
command removes the tab from the notebook and unmaps and unmanages the 
associated child widget. 

The inaex widget command returns an integer index of the tab, given any 
supported tab identifier; it returns the number of tabs managed if you 
provide ena as its argument. And the taos widget command returns a list of 
the widgets managed by the notebook. 

The notebook widget generates a <<notebooktabchangea>> Virtual event after a 
new tab is selected. See Chapter 22 for a discussion of virtual events. You 
can also enable keyboard traversal for a toplevel window containing a 
notebook widget with the following command: 


ttk:notebook::enableTraversal notebook 


This command automatically extends the bindings for the toplevel window 
containing the notebook to support the following behaviors: 
* ctrl+tab Selects the tab following the currently selected one 
* shift+ctri+tab Selects the tab preceding the currently selected one 
* ait+x, Where x is the underlined character specified by the -unaeriine 
option for a tab, selects that tab 


19.4 Progressbar 
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A ttk::progressbar widget provides some visual feedback to a user of the 
status of some long-running operation. The visual appearance of the 
progressbar is determined by its -orient option, which can be norizontal OF 
vertical, and its -1ength, which is a screen distance specifying the length of its 
long axis. Its behavior is determined by its -moae option, which can be set to 
determinate If 1t will indicate incremental progress to a known completion 
point, Or indeterminate 1f you can’t predict when the operation will complete. 

For a determinate progressbar, the -maximim option 1s a floating-point value 
indicating the completion point of operation. The default value for -maximum 1S 
100.0, Which is useful to represent a percentage; you could also provide a 
value representing an amount of time, some number of records to process, or 
some other benchmark. By setting the -vaiue option, you can then indicate 
how much progress your application has made toward the maximum. You 
can also accomplish this by invoking the ttk::progressbar’s step 
subcommand to increment the value by a given amount (which defaults to 


1.0)! 


progressbar step ?amount? 


Additionally, you can use the -variabie option to provide the name of a 
variable (referenced from the global namespace) with which you want the 
progressbar to synchronize its -vaiue option. 

With an indeterminate progressbar, you don’t have a predictable completion 
point for an operation; in this case the purpose of the progressbar is only to 
provide some visual indication to the user that the operation is ongoing and 
that the application hasn’t frozen. To use an indeterminate progressbar, 
simply invoke its start subcommand at the beginning of the operation and its 
stop Subcommand at the end. 


19.5 Separator 


The ttk::separator widget displays a simple horizontal or vertical separator, 
as specified by its -orient option. You can use it to provide a visual 
demarcation between logical sections in a complex interface. There are no 
interactive controls for the separator and no additional options of note. 


19.6 Sizegrip 
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The ttk::sizegrip widget implements a bottom right corner resize control. It 
allows the user to resize the containing toplevel window by pressing and 
dragging the grip. Proper sizegrip behavior is supported for only the bottom 
right corner of the toplevel. 

You must explicitly grid or pack the sizegrip in the correct position on the 
window. For example, if you use pack to position the sizegrip as part of a 
status bar at the bottom of a toplevel, you might use code such as 


set statusbar [ttk::frame $top.statusbar] 
pack S$statusbar -side bottom -fill x 

set grip [ttk::sizegrip $statusbar.grip] 
pack $grip -side right -anchor se 


On the other hand, if you use gria, your code might look like this: 


set grip [ttk::sizegrip $top.grip] 
grid $grip -row $lastRow -column $lastColumn -sticky se 


Note 


On Mac OS X, toplevel windows automatically include a built-in 
sizegrip by default. Adding +tx::sizegrip there 1s harmless, since the 
built-in grip just masks the widget. 


19.7 Treeview 


The ttk::treeview widget is a powerful tool for displaying one or more 
columns of information, optionally in a hierarchical arrangement with 
dynamic collapse and expand capabilities. 


19.7.1 Manipulating Treeview Items 


The fundamental building block of a treeview is an item, which represents 
one line of information in the treeview. Each item has a textual label, an 
optional image, and an optional list of data values that are displayed in 
successive columns of the treeview after the label. Each item must also have 
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a unique identifier within the treeview; you can either supply one yourself 
when creating the item or have the treeview assign an identifier 
automatically on creation. 

Items can be nested, so an item might serve as a simple leaf node, or it can 
serve as a parent with one or more child items beneath it. Each treeview has 
a root item created automatically when the treeview is instantiated; its 
identifier is the empty string. The root item itself 1s not displayed by the 
treeview. The direct children of the root item appear at the top of the 
hierarchy. 

You add items to a treeview widget using its insert subcommand: 


treeview insert parent index ?-id id? ?option value ...? 


The parent argument is the identifier of the parent item for the new item. The 
index 1§ the position of the new item within the parent; it can be a zero-based 
integer value, or the keyword ena to place the item after all existing children 
of the parent. You can explicitly provide a unique string identifier for the 
new item with the -ia option, or you can omit it to have the treeview 
automatically assign an identifier; the identifier 1s the return value of the 
command. Each item also supports a set of options that determine its 
appearance. You can set the options when you insert a new item, or 
afterward using the treeview’s item subcommand. You can also use the item 
subcommand to query one or all of the options for an item: 


treeview item id ?option? ?value option value ...? 


The supported item options are 
* -text—the text string to display for the item in the treeview 
* -image—the name of an optional image object to display to the left of 
the label 
* -values—a list of the values associated with the item 
* -open—a Boolean value indicating whether the item’s children should 
be displayed (true) or hidden (false) 
* -tags—a list of tags associated with the item, as discussed below 
For example, the following code creates a treeview and populates it with 
three toplevel items. It then creates several child items for each of the 
toplevel items: 
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ttk::treeview .tree -columns {capital} \ 

-xscrollcommand {.hbar set} -yscrollcommand {.vbar set} 
ttk::scrollibar .hbar -orient horizontal \ 

-command {.tree xview} 
ttk::scrollbar .vbar -orient vertical \ 

-command {.tree yview} 


grid .tree -row 0 -column 0 -sticky nsew 
grid .vbar -row 0 -column 1 -sticky ns 
grid .hbar -row 1 -column 0 -sticky ew 
grid columnconfigure . 0 -weight 1 

grid rowconfigure . 0 -weight 1 


tree insert {} end -id newengland -text "New England” 
.tree insert {} end -id midatlantic -text "Mid Atlantic" 
-tree insert {} end -id pacific -text "Pacific" 


set states { 


newengland me Maine Augusta 
newengland nh "New Hampshire" Concord 
newengland vt Vermont Montpelier 
newengland ma Massachusetts Boston 
newengland ri "Rhode Island" Providence 
newengland ct Connecticut Hartford 
midatlantic ny "New York" Albany 
midatlantic nj “New Jersey" Trenton 
midatlantic pa Pennsylvania Harrisburg 
pacific wa Washington Olympia 
pacific or Oregon Salem 
pacific ca California Sacramento 


} 


foreach {region id state capital} Sstates { 
.tree insert $region end -id $id -text $state \ 
-values [list $capital] 


.tree column #0 -minwidth 150 

.tree column capital -minwidth 150 
-tree heading #0 -text "State" 

.tree heading capital -text "Capital" 


The resulting treeview is shown in Figure 19.4. 


Figure 19.4 Example of a treeview widget 
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State | Capital 
Vv New England 


Connecticut Hartford 
Maine Augusta 
Massachusetts Boston 
New Hampshire Concord 
Rhode Island Providence 
Vermont Montpelier 
> Mid Atlantic 
¥ Pacific rt 
California Sacramento y 


You can programmatically expand or collapse an item by setting its -open 
property to true or false, respectively. Default treeview widget class 
bindings automatically implement collapse/expand behavior for user 
interaction; clicking the left mouse button on an item toggles the item’s -open 
option. The widget also generates <<rreeviewopen>> and <<treeviewClose>> Virtual 
events in response to these actions, and you can implement your own custom 
item open/close behaviors. See Chapter 22 for more information on virtual 
events and executing scripts in response to events. You can also use the 
treeview’s see Subcommand to ensure that a specific item is visible; it sets 
all of the item’s ancestors to -open true and scrolls the widget if necessary so 
that the 1tem is displayed on the screen: 


treeview see item 


You can use the move subcommand to move an existing item to a new location 
in the item hierarchy: 


treeview move item parent index 


The item argument is the identifier of the existing item to move, and the parent 
and index arguments are interpreted as with insert. You cannot move an item 
under one of its descendant items. 

The aeiete Subcommand takes a list of one or more item identifiers and 
deletes each of them and all their descendant items. In contrast, the aetach 
subcommand takes a list of item identifiers and “unlinks” them from the tree. 
The items and their descendants are no longer displayed by the tree, but they 
still exist. You can reattach any of them to the tree in any location by using 
the move subcommand. 

You can determine the integer index of an item within its parent using the 
index SUbcommand. The next and prev Subcommands return the identifier of an 
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item’s next or previous sibling; these return an empty string if the item is the 
last or first item within a parent, respectively. The parent subcommand 
returns the identifier of an item’s parent, or an empty string if the item is at 
the top of the hierarchy. The chitaren subcommand returns a list of identifiers 
of all of the children of an item in the order in which they appear; you can 
also provide a list of item identifiers, in which case the existing children are 
detached and the items listed become the new children. 


19.7.2 Managing Treeview Columns and Headings 


Your treeview can display as many columns of data as you like. The first 
column consists of the tree items themselves; that column displays the image 
associated with the item followed by its text label, as specified by the 
item’S -image and -text properties, respectively. Both of these properties are 
optional. Additional columns display elements from the item’s optional - 
values property. Columns also have configurable headings. 

The treeview widget’s -colums property determines the number of columns 
of data contained within the treeview. Its value is a list of logical column 
names. The default value for -coiums is an empty list, which indicates that 
the treeview displays a single column containing the tree items and that the - 
values property of the items is ignored. If a list of logical column names is 
provided for -coiumns, the list elements of each item’s -vaiues property are 
associated with the corresponding logical column names in order. If the - 
values list contains fewer elements than logical columns, an empty string 
value is assumed for the remaining columns; if the list contains more 
elements than logical columns, the excess elements are ignored. The 
example in Section 19.7.1 defined a single logical column named “Capital,” 
and each item had a one-element list for its -vaiues property, providing the 
value for that column. The following code defines a treeview widget with 
three logical columns named country, capitai, aNd currency and defines several 
items, each with three corresponding values for its -values property: 


ttk::treeview .tree -columns {country capital currency} 
end -values {Canada Ottawa CAD} 
end -values {France Paris EUR} 


.tree insert {} 
.tree insert {} 
.tree insert {} end -values {Germany Berlin EUR} 
.tree insert {} end -values {Japan Tokyo JPY} 


The order in which the logical columns are displayed does not have to be 
the same as the order in which they appear in -columns. You can also 
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configure the treeview to show only a subset of the logical columns. This 
behavior is controlled by the treeview’s -aispiaycolumns property. You can set 
it to a list of the logical column names (or their zero-based indices) in the 
order in which they should be displayed. The default value for -aispiaycoiumns 
1S #a11, which indicates that all logical columns should be displayed in the 
order in which they were defined. 

The tree items always appear in the first display column. You cannot display 
them in a different column, but you can choose not to display them. The 
treeview’s -show property contains a list specifying which elements of the 
treeview to display. The default value is (tree headings}, to display both the 
tree items and the column headings. 

The co1um. command queries or modifies display column configuration: 


treeview column column ?option? ?value option value ...? 


You can specify a column by the logical column name if it is displayed; you 
can also use the zero-based logical column index identifying the column as 
listed in the -coiums property. Alternatively, you can indicate a display 
column with a string in the form #n, where » is the zero-based column 
number counting from the left. 


Note 


Column #0 always refers to the tree column, even if it is not displayed. 


The supported column options are 
* -ia—a read-only option containing the logical column name 
* -anchor—Specifies how the text in this column is aligned with respect 
to the cell; one of n, ne, ¢, se, s, sw, w (default), nw, Or center 
* -minwidth—the minimum width of the column in pixels; defaults to 20 
* -stretch—a Boolean specifying whether or not the column’s width 
should be adjusted when the widget is resized; defaults to 1 (true) 
* -wiath—the width of the column in pixels; defaults to 200 
You query or modify column headings with the neaaing command: 


treeview heading column ?option? ?value option value ...? 


The supported heading options are 
* -text—the text to display in the column heading 
* -image—an image to display to the right of the column heading 
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* -anchor—sSpecifies how the heading text should be aligned; one of », ne, 
e, se, Ss, sw, wy nw, OF center (default) 
* -command—a Script to evaluate when the heading label is pressed 


19.7.3 Treeview Item Selection Management 


The default treeview widget class bindings automatically handle selecting 
an item when the user clicks on the item. However, the way the bindings 
behave depends on the value of the treeview’s -se1ectmode option: 

® extended (default) 
Clicking an item selects it and deselects any other items currently selected. 
The user may select multiple items, using Control-clicks to toggle an item’s 
selection and Shift-clicks to extend the selection. 

*° browse 
Clicking an item selects it and deselects any other items currently selected. 
At most one item may be selected by the user. 


® none 


Clicking items does not affect which items are selected. Thus, this disables 
direct user selection of items. 

The -seiectmode option affects only the user’s ability to manage treeview item 
selection. Regardless of the -seiectmoade value, your application can use the 
treeview’s selection Subcommand to control item selection: 


treeview selection ?selectOp itemList? 


Without any additional arguments, the seiect subcommand returns a list of 
selected items. The seiection set Subcommand causes itemzist to be the new 
selection; providing an empty itemzist removes all items from the selection. 
The selection aaa SUbCommand adds the items in itemzist to the selection; the 
selection remove SUbcommand removes the items in itemzist from the selection; 
and the seiection toggle Subcommand toggles the selection state of each item 
IN itemzist. 

The treeview widget also generates a <<treeviewselect>> Virtual event 
whenever an item is selected or deselected. See Chapter 22 for more 
information on virtual events and executing scripts in response to events. 


19.7.4 Treeview Item Tags 


The treeview widget allows you to define symbolic tags that you can apply 
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to any number of items. Tags allow you to apply formatting to individual 
items in the treeview. You define, query, or modify tag properties with the 
tag configure subcommand: 


treeview tag configure tag ?option? ?value option value ...? 


The supported tag options are 
® -packgrouna—the background color to use for the cells displaying the 
items 
* -foregrouna—the text foreground color for the items 
* -font—the text font for the items 
* -image—an image to display for the items, but only if an item does not 
have its OWN -image property set 
All tag options have a default value of the empty string, which indicates that 
the tag does not affect that aspect of an item. As an example, the following 
code defines two tags named hightignht and important: 


.tree tag configure highlight \ 
background blue -foreground white 
-tree tag configure important -foreground red 


To apply tags to an item, you provide a list of tag names as the value of the 
item’s -tags property; for example: 


.tree item vt -tags {highlight important} 


The tags are listed in order from lowest priority to highest priority. If 
multiple tags have the same tag option set, the value for the tag with the 
highest priority is used. For example, because important 1s listed after 
highlight 1n the preceding line of code, its foreground color of rea is used for 
the vt item. But because important does not set a value for its -packgrouna 
property, the niue value set by the nighiight tag is used in this case. 

The treeview widget also allows you to associate bindings to tags with the 
tag bina SUbCommand. You can use bindings to make items “active” so that 
they respond to mouse, keyboard, or virtual events. (See Chapter 22 for 
more information on events and executing scripts in response to events.) 
Among other things, this enables you to implement hypertext effects. For 
example, the following binding simply prints a message to the console 
whenever the user clicks on an item that has the tag important: 


.tree tag bind important <ButtonPress-1> { 
puts "This is an important item" 


448 


Keyboard events trigger a tag binding only when the item has focus. At most 
one item at a time in a treeview has focus. The default treeview widget 
class bindings automatically assign focus to the last item selected by the 
user. You can use the socus subcommand to query or set the focus item: 


treeview focus ?item? 


Called without an item, the command returns the identifier of the current 
focus item or an empty string if no item has focus. Called with an item 
identifier, the command assigns focus to the specified item. 

It is possible for multiple bindings to match a particular event, for example, 
if you’ve created bindings for multiple tags and then applied some 
combination of those tags to an item. When this occurs, all of the matching 
bindings are invoked, in order from lowest-priority to highest-priority tag. If 
there are multiple matching bindings for a single tag, only the most specific 
binding is invoked. A continue command in a binding script terminates that 
script, and a preax command terminates that script and skips any remaining 
scripts for the event, just as for the bina command. 


Note 


If bindings have been created for a treeview widget using the bina 
command, they are invoked in addition to bindings created for the tags 
using the tag bina subcommand. The bindings for tags are invoked 
before any of the bindings for the widget as a whole. 


19.8 Themed Widget States 


The state of a widget controls its appearance and behavior. The state of a 
classic widget is determined by the value of its -state option, as described 
in Section 18.15.1. Most classic widgets support only the values norma: and 
disabled, but some widgets, such as the entry and spinbox, support additional 
states such as readonly. A classic widget can be in only one state at a time. 

Themed widgets also use states, but these differ from classic widgets in two 
important ways. First, states consist of several independent flags, each of 
which may simultaneously be on or off; the complete state for the widget is 
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therefore equivalent to the particular combination of flags that are on or off. 
Second, all themed widgets support states, and all widgets use exactly the 
same set of state flags, though as we’ll see, some flags may be ignored by 
particular widgets. All themed widgets currently support the following 
States: 

® active 
The mouse cursor is over the widget, and pressing a mouse button will 
cause some action to occur. 

° disabled 
The widget is disabled under program control. 

* focus 
The widget has keyboard focus. 

® pressed 


The widget is being pressed. 
® selected 


The widget is “on, 
radiobuttons. 


99 66 


true,” or “current” for things like checkbuttons and 


® background 
Windows and Mac OS X have a notion of an “active” or foreground 
window. The vackgrouna State is set for widgets in a background window and 
cleared for those in the foreground window. 

® readonly 
The widget should not allow user modification. 

* alternate 
This is a widget-specific alternate display format. For example, it is used 
for checkbuttons and radiobuttons in the “tristate” or “mixed” state, and for 
buttons that have their -caerauit option Set to active. 

° invalid 
The widget’s value is invalid (for example, if an entry widget value fails 
validation). 
For each themed widget in your application, some of these states might be 
“on” or “set,” while the others are “off’ or “unset.” Default bindings for 
each of the themed widget classes automatically manage the states. For 
example, the rsutton class (themed button) has default bindings that check 
whether the aisabiea State of a themed button is “off”; if so, they set the active 
state to “on” when the mouse enters the button and back to “off’ when the 
mouse leaves the button. You can programmatically change and query the 


state of a themed widget using its state widget command: 


widget state ?stateSpec? 
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The statespec 18 a list of states to set or unset. If an element consists of a state 
name, the state is set; if an element consists of a state name preceded by a |, 
the state is unset. The return value indicates which flags were changed. If 
you execute the state widget command with no statespec, 1t returns a list of 
the states currently set; for example: 


.@ state {focus readonly} 
=> !focus !readonly 
.@ state 
= focus readonly 
.@ state {!focus !readonly disabled} 
=> !disabled focus readonly 
-@ state 
= ats 


You can test the state of a themed widget using its instate widget command: 


widget instate stateSpec ?script? 


Without a script argument, the command returns : if the widget state matches 
the statespec, or 0 otherwise; for example: 


.@ instate disabled 


YJ 


.e instate {disabled ! readonly} 


.@ instate alternate 
=: 


If you provide a script argument, the script is executed if the widget state 
matches the state specification. For example, the following invokes a 
themed button, .», only ifit 1s currently pressed and enabled: 


.b instate {pressed !disabled} { .b invoke } 


Note 


The instate widget command allows you to create widget or even class 
bindings implementing state-based behaviors quite easily. As you will 
see in Section 19.9.3, the ttk::styie map command also allows you to 
change the appearance of widgets in particular states. In combination, 
this allows significant customization of the out-of-the box widget set 
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with no need to modify the underlying code implementing the widgets. 


19.9 Themed Widget Styles 


Each themed widget is assigned a style, which specifies the appearance of 
the widget under different circumstances. Remember that each widget has a 
default class associated with it (e.g., rrabe1 for all label widgets). The 
default style associated with a themed widget has the same name as the 
widget class (e.g., a style named riabe1). Thus, all themed widgets of the 
same class have the same appearance, unless your application explicitly 
overrides the style for a widget. 

You can use the winfo class command to determine the class of a particular 
widget; for example: 


ttk::label .1l 
winfo class .l 
=> TLabel 


You can override the default style of a themed widget by assigning the style 
name as the value of the widget’s -styie property. (The default value is an 
empty string, which indicates that the widget uses the default style as 
defined by the class name.) For example, if you have defined a new style 
named aiertiabel.tTLabe1, yOu could assign it to a widget as follows: 


.l configure -style AlertLabel. TLabel 
You will see how to define new styles in the following sections. 


19.9.1 Using Themes 


A theme is a named collection of styles, designed to provide a consistent 
look and feel to all the themed widgets in an application. The ttx::styie theme 
names Command lists the names of themes defined on your current system: 


ttk::style theme names 
=> aqua clam alt default classic 


Tk automatically picks an appropriate theme for your windowing system 
when you launch the application. The ttx::currenttheme variable contains the 
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name of the current theme: 


puts $ttk::currentTheme 
=> aqua 


You can switch to a different theme by executing ttk::style theme use! 


ttk::style theme use clam 


This command updates all styles with the definitions from the new theme 
and refreshes all themed widgets to reflect the new theme. 


19.9.2 The Elements of Style 


A themed widget is implemented internally as a collection of elements. One 
function of a style is to control the placement of elements. 


Note 


In general, application developers rarely modify widget layouts. 
However, it can be useful to determine the elements that compose a 
particular themed widget when you want to customize its configuration, 
as discussed in the next section. 


You can use the ttx::style layout Command to view or change the layout of 
elements for a given style. Here is an example under the Aqua theme: 


ttk::style layout TCheckbutton 
=> Checkbutton.button -sticky nswe -children {Checkbutton. padding 


-sticky nswe -children {Checkbutton.label -side left -sticky {}}} 


A layout consists of a list of elements, each followed by one or more 
options specifying how to arrange the elements. In the return value above, 
Checkbutton.button, Checkbutton.padding, @Nd checkbutton.labe: are the elements 
composing a themed checkbutton widget under the Aqua _ theme. 
Reformatting the output can make the structure clearer: 
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Checkbutton.button -sticky nswe -children { 
Checkbutton.padding -sticky nswe -children { 
Checkbutton.label -side left -sticky {} 


} 


} 


The elements are arranged in the order listed within the space allocated to 
the widget, known as the cavity. The optional -sice property determines the 
location of the parcel of space allocated to the element, and it can be set to 
one Of ieft, right, top, OF bottom. If you omit the -siae property, the entire cavity 
is allocated to the element. The -sticxy option specifies where the element 
resides in its parcel by indicating the sides of the parcel to which the 
element “sticks.” For example, the -sticky nswe option in the preceding 
example indicates that the element should fill all of the parcel. The -cnitaren 
property specifies a list of one or more elements arranged inside the parent 
element, following the same rules discussed before. 

Note that the layout for a particular style might vary from one theme to 
another. This is because some windowing systems use elements on widgets 
(such as focus indicators) that aren’t used by other windowing systems. For 
example, under the Aqua theme, the rautton layout is defined as follows: 


Button.button -sticky nswe -children { 
Button.padding -sticky nswe -children { 
Button.label -sticky nswe 
j 
J 


In contrast, the rsutton layout has the following definition under the XP 
native theme: 
Button.button -sticky nswe -children { 
Button.focus -sticky nswe -children { 


Button.padding -sticky nswe -children { 
Button.label -sticky nswe 


19.9.3 Creating and Configuring Styles 


As an application developer, you might want to change the appearance of 
various widgets in your application, for example, setting the foreground 
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color used to render text in a set of buttons. Rather than requiring you to set 
the configuration options on each individual widget, themed widgets allow 
you to set the configuration options for the style, which then takes effect 
automatically for each widget that uses that style. 

Before you can configure the options associated with a style, you need to 
know what options are available on that style. Each element that is a 
component of a themed widget has a set of options that it uses. You can 
retrieve a list of the options associated with a given element using the 
ttk::style element options Command, like so: 


ttk::style element options TLabel.label 
=> -compound -space -text -font -foreground -underline -width -anchor 
-justify -wraplength -embossed -image -stipple -background 


The actual values for element options are supplied by the style containing 
the element, or in some cases (for example, -text) by the actual instance of a 
themed widget. When configuring a style, you can provide values for any of 
the options associated with any of the style’s elements. A single option, such 
aS -backgrouna, might be associated with several elements within a style. In 
that case, the value provided by the style would be used by all of the 
associated elements. This feature ensures visual consistency in the widget. 

The ttx::style configure Command queries or modifies the option values of a 


style: 


ttk::style configure style ?option? ?value option value ...? 


For example, you could configure the riapei style so that every themed button 
in your application displays its text in green: 


ttk::style configure TLabel -foreground green 


More typically, you might want a customization to apply to only some of the 
widgets of a particular class in your application. For example, you might 
want most of your labels to use the standard colors defined by the theme, but 
some labels are special alerts that should use red text. In that case, you can 
define a new style derived from the rrabe1 style, as in the following example: 


ttk::style configure AlertLabel. TLabel -foreground red 


The style name aterttabel.tLabe1 Indicates that it is derived from rrabei. If an 
element queries the -foregrouna option, it gets the value rea; if it queries any 
other option, it gets any value configured in the riave1 base style. You can 
create as deep a hierarchy of derived styles as you like, using a . to separate 
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each level. When an element queries an option, it obtains the value from the 
first style where it is defined. There is also a base style named . that is used 
to provide default option values for all styles. The primary purpose of the . 
style is to serve as a fundamental building block for defining the look and 
feel of a theme. 

The option values you set with the ttx::styie configure Command are the 
default values that apply. However, you can also use the ¢ttx::style map 
command to define override values to use depending on the state of the 
widget: 


ttk:style map style ?option? ?{stateSpec value ...\ ...? 


The styie and option arguments are interpreted as with ttx::style configure. The 
next argument is a list of state specifications (expressed in the same format 
as described in Section 19.8) and corresponding option values. The actual 
state of a particular widget is compared against the state specifications in 
the order in which they are listed. The first specification that matches the 
widget’s state determines the value to use for the option. State maps are 
inherited as well, so if there is no appropriate mapping for an option in the 
current style, the style from which it was derived is then checked, and so on. 
If none of the state specifications matches, the option gets the default value 
as defined by the ttx::style configure definitions described earlier. 

The ttk::style lookup command allows you to retrieve the value of a 
particular option for a style: 


ttk::style lookup style option ?stateSpec ?default?? 


With no statespec OF default arguments, the command returns the default value, 
as defined by ttk::style configure. For example, to retrieve the default button 
font: 


ttk::style lookup TButton -font 
= TkDefaultFont 


Given a statespec, the command returns a value using the standard lookup 
rules for element options (that is, checking for a matching ttx::style map State 
specification first and falling back to the defaults defined by ttx::styte 
configure If there 1s no matching state specification). If the cerauit argument is 
present, it is used as a fallback value in case no specification is found for 
the option. 
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19.10 Other Standard Themed Widget Options 


Like classic widgets, themed widgets support options that control their 
appearance and behavior. The configuration options for a themed widget 
may be specified when the widget is created and modified later with the 
configure Widget command; you can query the value of a widget’s 
configuration option using the cget widget command. 

The standard set of options supported by themed widgets is much smaller 
than the set for classic widgets. Unlike classic widgets, most themed 
widgets don’t support options such as -packgrouna, -relief, OF -font for 
controlling color, borders, or fonts. Instead, these visual characteristics are 
controlled by the widget’s style, which is usually determined by the overall 
theme selected for the application. Styles are discussed more in Section 
ie. 

Themed widgets support a -cursor option, which controls the appearance of 
the mouse cursor when the mouse is over the widget, and it works just as 
with classic widgets, as discussed in Section 18.15.5. Scrollable themed 
widgets also support -xscrolicommand and -yscrollcommana Options and follow the 
same scrolling protocols described in Section 18.9. 

Labels, buttons, and other button-like themed widgets support -text and - 
textvariable Options that behave like their classic counterparts. These 
widgets also support a -image option for specifying the name of an image 
object to display. However, rather than being limited to a single image 
name, themed widgets allow you to specify a list of values for the -image 
option. The first element is the name of the default image to display. 
Subsequent elements are two-element nested lists, where the first element is 
a State specification, as defined in Section 19.8, and the second element is 
the name of an image to display in that state. The first state specification that 
matches the widget’s current state determines the image to display. All 
images should have the same size. 

The -compouna option determines how to position the image relative to the 
text, if both have been specified for a widget. The default of none displays 
the image if present, otherwise the text. A value of text OF image displays only 
one or the other type of content. A value of top, vottom, left, OF right places the 
image in the indicated position relative to the text. A value of center displays 
the text centered on top of the image. 
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20. Fonts, Bitmaps, and Images 


The primary function of any graphical interface is to present text and 
pictures, and the resources needed to accomplish this are fonts and images. 
Available fonts vary greatly from one platform to another, and even from 
one Windows PC to another. Having a way to manage font usage in an 
application simplifies supporting multiple platforms and multiple 
environments. Tk provides the sont command to create named fonts and to 
manage font use in applications. Likewise, icons have become as important 
as any glyph in any alphabet in today’s applications. These images, some of 
which are common and some of which are unique, are necessary in any 
application with a graphical user interface. The Tk image command is used to 
load, manipulate, and share image data within applications. In this chapter 
we present these two commands. 


20.1 Commands Presented in This Chapter 


This chapter discusses the following commands for manipulating fonts and 
images: 

® font actual font ?-displayof window? ?option? ?--? ?char? 
Returns the actual attribute values for a font. The actual values can vary 
from what was specified because of platform limitations. The options are 
the same as those supported for font configure. 

* font configure fontname ?option? ?value option value ...? 
Queries or configures the attributes for a named font. If a single option is 
specified with no vaiue, it returns the current value of that attribute. If one or 
More option value pairs are specified, the command modifies the given named 
font to have the given values. See the text and the reference documentation 
for a description of the supported attributes and their values. 

® font create ?fontname? ?0ption value ...? 
Creates a new named fontname with the attributes specified by the option vaiue 
pairs and returns its name. If fontname 1s omitted, Tk generates a new name. 
The options are the same as those supported for font configure. 

® font delete fontname ?fontname ...? 
Deletes the specified named fonts. 


* font families ?-displayof window? 
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Returns a list of the case-insensitive names of all font families that exist on 
window S display. 

© font measure font ?-displayof window? text 
Measures the amount of space the string text would use in the given font 
when displayed in window. The return value is the total width in pixels of text, 
not including the extra pixels used by highly exaggerated characters such as 
cursive f. Format control characters like newline and tab are ignored. 

® font metrics font ?-displayof window? ?option? 
Returns information about the metrics for fone when it is used On winaow’s 
display. See the reference documentation for more information. 

* font names 
Returns a list of all the named fonts currently defined. 

® image create type ?name? ?option value ...? 
Creates a new image Of type bitmap OF photo. A name is created automatically 
if name 18 Omitted. Returns the name of the image created. Also creates a 
command of the same name for further image access. See the text and the 
reference documentation for information on the supported options. 

® image delete ?name ...? 
Deletes each of the named images. Each instance where the image is 
displayed retains its size, but the area goes blank. The actual image 1s not 
deleted until all the instances are released. 

® image height name 
Returns the height of the image in pixels. 

® image inuse name 
Returns a Boolean value indicating whether the image is in use by any 
widgets. 


° image names 


Returns a list containing the names of all existing images. 


° image type name 


Returns the type of the image name, for example, bitmap OF photo. 


image types 
Returns a list whose elements are all the valid values for the type parameter 
to the image create command. 


° image width name 


Returns the width of the image in pixels. 


20.2 The «1 Command 


While Mac OS X and Windows specify fonts using the same nomenclature, 
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X-based windowing systems use a distinctly different naming scheme. With 
X, the font name specifies a number of parameters, such as 


-adobe-times-bold-r-normal-18-180-75-75-p-99-iso8859- 1 


This font name specifies a Times Bold font from Adobe, at 18 point, 
designed for a 75 DPI screen and supporting the Western European ISO- 
8859-1 character set. Mac OS X and Windows specify fonts using much 
shorter names, like the following: 


Times Bold 18 


Tk abstracts out this difference by using named fonts. Tk widgets accept 
fonts specified in any one of five different forms; however, the best way to 
use Tk is with named fonts. In this way, platform variations are easily 
isolated. 


Note 


If the master font that you set for a widget doesn’t contain a glyph for a 
particular Unicode character that you want to display, Tk attempts to 
locate a font that does. Where possible, Tk attempts to locate a font that 
matches as many characteristics of the widget’s master font as possible 
(for example, weight, slant, etc.). Once Tk finds a suitable font, it 
displays the character in that font. In other words, the widget uses the 
master font for all characters it is capable of displaying and alternative 
fonts only as needed. In some cases Tk is unable to identify a suitable 
font, in which case the widget cannot display the characters. Instead, 
the widget displays a system-dependent fallback character such as >. 


Tk comes with a predefined set of named fonts on all platforms that match 
appropriate system defaults. You should not change these fonts, as Tk itself 
may modify them in response to system changes. The font names and their 
default/recommended uses are as follows: 

* vkDefaultront—the default for all GUI items not otherwise specified 

* TkTextFont—font used for user text in entry widgets, listboxes, etc. 

* vkFixedFont—the standard fixed-width font 

* vkMenuFont—font used for menu items 

* TkHeadingront—font used for column headings in lists and tables 

* TkCaptionront—font used for window and dialog caption bars 
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* TksmallCaptionront—font used for captions on contained windows or 
tool dialogs 

* vkIconFont—font used for icon captions 

* tkTooltipront—font used for tooltip windows (transient information 
windows) 


20.2.1 Manipulating and Using Named Fonts 


To use a named font, you first create a new font, giving it the name you want 
to use. When you create the font, you specify the font family, size, and so on, 
using the font create Command: 


font create ?fontname? ?option value ...? 


You can either provide a specific fontname for the named font, or you can 
have font create automatically assign a name consisting of font followed by a 
unique integer. The return value is the name of the font created. The option 
value pair arguments that follow specify the characteristics of the font. You 
can use any of the following options to configure the font: 

© -family name 
The case-insensitive font family name. Tk guarantees to support the font 
families named Courier, Times, and Helvetica. The most closely matching 
native font family is substituted automatically when one of these font 
families is used. The name may also be the name of a native, platform- 
specific font family. If the family is unspecified or unrecognized, a platform- 
specific default font is chosen. 
The desired size of the font. A positive size argument is interpreted as a size 
in points. A negative size number is interpreted as a size in pixels. If a font 
cannot be displayed at the specified size, a nearby size is chosen. If size 1s 
unspecified or zero, a platform-dependent default size is chosen. 

° -weight weight 
The nominal thickness of the characters in the font. Valid values are normai to 
specify a normal-weight font and bo1a to specify a bold font. 

® -slant slant 
The amount the characters in the font are slanted away from the vertical. 
Valid values for siant are roman and italic. 

® -underline boolean 


The value is a Boolean flag that specifies whether characters in this font 
should be underlined. 
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® -overstrike boolean 


The value is a Boolean flag that specifies whether a horizontal line should 
be drawn through the middle of characters in this font. 

For example, the following creates a font called Lopstera01a based on the 
Helvetica font: 


font create LobsterBold —family Helvetica \ 
-size 12 -slant roman -weight bold 


After you have created a named font, you can use it anywhere that Tk 
accepts a font, such as the -font attribute of particular widgets or the -sont 
attribute of tags in a text widget: 


-mylabel configure -font LobsterBold 


After you have defined a named font, you can later modify its definition 
using the font configure command: 


font configure fontname ?option? ?value option value ...? 


You can change any of the attributes of a named font by providing values for 
the specified options. The options supported are the same as for font create. 
If you provide the name of only one option with no new value, the font 
configure Command returns that attribute’s current value. If you provide only 
the font name as an argument, the command returns a dictionary of all font 
attributes and their values. 

When you uSe font configure to change the definition of a named font, all 
widgets in your application that use the named font immediately update to 
reflect the change. Thus, the following command would cause all widgets 
that use the LopsterBo1a font to reduce the text they display to 10 points: 


font configure LobsterBold -size 10 


The font names Command returns a list of all named fonts. The font actuat 
command allows you to determine the actual attributes of the named font. 
These might differ from the requested values if, for example, the requested 
font family or other font attributes are not available on the local system. The 
following example shows how the Arial font was substituted for Helvetica 
in the definition of nopsternoia on a Windows system: 


font actual LobsterBold 


Sie ie tray Peete ee . ’ pine ey 1h meee ae 
=> -family Arial -size 10 -weight bold -slant roman -underline 0 


away ae f) 
“overstrixe vV 
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The font deiete command deletes one or more named fonts. If there are 
widgets using a named font that has been deleted, the named font isn’t 
actually deleted until all the instances are released. Those widgets continue 
to display using the last known values for the named font. If a new named 
font is created with the same name while there are widgets still using the 
former named font, the widgets redisplay using the new attributes of the font. 
The following script shows how to create named fonts in Tk as well as 
change the size of the font: 


4 
# Demonstrate named fonts 


set top [toplevel .dialog] 

set icon [label $top.icon -bitmap info] 

set 1 [label $top.msg -textvariable message] 
set message "Named Font Demonstration" 

set defaultFont [$l cget -font] 

set £ [frame $top.f] 


set bDefault [button §f.def -text A -command \ 
"“configDefault" -font {helvetica}] 

set bSmaller [button $f.sm -text A -command \ 
“configSize -2" -font {helvetica 10}] 

set bBigger [button $f.bg -text A -command \, 
"configSize +2" -font {helvetica 18}] 


pack $bDefault S$bSmaller $bBigger -side left -pady 5 -padx 5 


grid Sicon -row 0 -colum 0 -padx §& -pady 10 

grid $1 -row 0 -column 1 -sticky ew -padx 5 -pady 10 
grid $f - -row 1 

set defaultSize [font actual $defaultFont -size) 


set defaultFamily [font actual $defaultFont -family] 
set defaultWeight [font actual $defaultFont -weight] 


464 


set size 18 

set family Helvetica 

set weight bold 

font create LobsterBold -size $size -family $family \ 
-weight bold 

$1 configure -font LobsterBold 


proc configDefault {} { 
font configure LobsterBold \ 
-family $::defaultFamily \ 
-size $::defaultSize \ 
-weight $::defaultWeight 
set ::message "Default Font" 


} 


proc configSize {delta} { 
font configure LobsterBold \ 
-family Helvetica \ 
-size [expr {[font actual LobsterBold -size] + $delta}] 
if {$delta < 0} { 
set ::message "Smaller Font" 
} else { 
set ::message "Bigger Font" 
} 


puts "font size is [font actual LobsterBold -size]" 


} 


Figure 20.1 shows the result of running this script, with three different 
screen shots reflecting the results of pressing the buttons to change the font 
configuration. 


Figure 20.1 Examples of changing named font configuration 


20.2.2 Other Font Utilities 


In addition to manipulating named fonts, the sone command provides 
additional subcommands for querying information about fonts. 

The font families Command returns a list of all font families that are 
available. For systems with multiple displays, different sets of fonts might 
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be available on different displays, so the command supports the -aispiayor 
option, allowing you to provide a widget name to retrieve the list of font 
families available on the display where the widget appears. The command 
defaults to using the main display if you don’t provide the -aispiayor option. 
The font families Command is useful for creating font selector menus or 
dialogs to allow the user to choose a font for use in your application. 

The font measure Command returns the width in pixels that a string would use 
if displayed in a given font: 


font measure times "This is a text" 
=>67 


20.2.3 Font Descriptions 


As mentioned earlier, fonts have five possible formats in Tk. Any of these 
may be used wherever a font may be specified, either in a window property, 
in a text or canvas widget tag property, or in the font command. The five 
formats are as follows: 

* fontname 
The name of a named font, created using the font create command. Named 
fonts always work without error. If the named font cannot be displayed with 
exactly the specified attributes, some other close font is substituted 
automatically. 

© systemfont 
The platform-specific name of a font, interpreted by the windowing system. 
This also includes an XLFD under X (see below). Tk provides a set of 
predefined named fonts that are mapped to system fonts. See the reference 
documentation for details. 

° family ?size? ?style? ?style...? 
A properly formed list where the first element is the font family and the 
optional second element 1s the size. The size attribute follows the same rules 
described for the -size attribute for font configure. Any additional arguments 
following the size are font styles. Possible values for styie are normal, bold, 
roman, italic, underline, AN overstrike. 

¢ X-font names (XLFD) 
A Unix-centric font name of the form 


-foundry-family-weight-slant-setwidth-addstyle-pixel-point 
-resx-resy-spacing-width-charset-encoding 


466 


The » character may be used to designate default values for a field. There 
must be exactly one + for each default field, except that a « at the end of the 
XLFD defaults any remaining fields; the shortest valid XLFD 1s simply +, 
signifying all fields as defaults. 

© option value ?o0ption value ...? 
A properly formed list of option vaiue pairs that specify the attributes of the 
font, in the same format as is used with font configure. 
When a font is specified, Tk parses it and attempts to identify the font using 
the five preceding rules, in order. For the first two cases, the name must 
match exactly. For the remaining three cases, the closest available font is 
used and, failing that, a system-dependent default 1s chosen. If a font 
description does not match any of these patterns, an error is generated. 


20.3 The inase Command 


The Tk image command is used to create and manage images. It works by 
creating an image object, which is then passed to widgets via the -image or - 
bitmap Options or manipulated through the object’s subcommands. When an 
image is created, a new command is created whose name is the same as the 
name of the image. This command is then used to manage the pixel data in 
the image. 


Note 


By default, the image command is created in the global namespace. The 
newly created image command also overwrites any existing command of 
that same name. Be careful when selecting image names not to 
overwrite existing commands, or else let image create aSsign image 
names for you. One way to manage image names is to use fully 
qualified namespace names for the images, as discussed in Section 
20,33: 


There are two built-in types of images: pitmap, for two-color images, and 
photo, for multicolor images. New types can be defined using the 
Tk CreateImagetype C API as an extension. The Img extension, for example, 
defines a type pixmap for X11 pixmap images. The photo image type can also 
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be extended via the rx createPhototmagerormat C API, to provide support of 
different data formats. The Img extension does this as well to support a 
variety of formats other than those built into Tk. 

A bitmap image is defined with a simple bit plane specifying on/off or 
foreground/background colors coupled with a mask. The mask defines the 
area of the image to be displayed while the rest of the area is transparent, 
where the underlying widget shows through. There are a few places in Tk 
where only bitmap images can be used, for example, the wm iconbitmap 
command. This command defines the icon used in the windowing system 
when the window is minimized. (Some windowing systems allow only 
simple bitmaps in this situation.) 

The second type of image is a photo. The photo image is a full-color (32 
bits per pixel) image internally and is displayed using dithering if necessary. 
Tk has built-in support for images created from GIF and PPM/PGM file 
formats, and extensions add support for other formats. The two built-in 
image types are discussed in more detail in the following sections. 


20.3.1 Bitmap Images 


You create bitmap images with the bitmap type argument tO image create! 
image create bitmap ?name? ?option value ...? 


You can either provide a specific name for the bitmap or have image create 
automatically assign a name consisting of image followed by a unique integer. 
The return value is the name of the bitmap image created. The option vaiue 
pair arguments that follow specify the characteristics of the bitmap. You can 
use any of the following options to configure the bitmap: 

® -background color 
Specifies a background color for the image. If this option is set to an empty 
string, the background pixels are transparent. This effect is achieved by 
using the source bitmap as the mask bitmap, ignoring any -maskaata OF - 
maskfile Options. 

® -data string 
Specifies the contents of the source bitmap as a string in the X11 bitmap 
format. If both the -aata and -riie options are specified, the -aata option takes 
precedence. 

° -file fileName 
Gives the name of a file whose contents define the source bitmap in the X11 
bitmap format. 
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*° -foreground color 
Specifies a foreground color for the image. 


® -maskdata string 


Specifies the contents of the mask as a string in the X11 bitmap format. If 
both the -maskaata and -maskfile Options are specified, the -maskdata option 
takes precedence. 


© -maskfile fileName 


Gives the name of a file whose contents define the mask in the X11 bitmap 
format. 

For the bitmap type, the image command returned by image create Supports 
two subcommands, cget and configure. The cget subcommand returns the 
current value of the specified option. The conrigure subcommand queries or 
modifies the options specified or returns a list of all the options and their 
values if no arguments are given. A bitmap image can be used with any 
widget that supports a -bitmap option. 


20.3.2 Photo Images 


Photo images are full-color images. The image create photo Command creates 
an image object and a Tcl command for manipulating the image. The image 
create Command accepts these options for the photo type: 

® -data string 
Specifies the contents of the image as a string. The string can contain 
base64-encoded data or binary data. The format of the string must be one of 
those for which there is an image file format handler that accepts string data. 

° -format formatName 
Specifies the name of the file format for the data specified with the -aata or - 
file Option. 

° -file fileName 
Gives the name of a file containing data for the photo image. The file format 
must be one of those for which there is an image file format handler that can 
read data. 

° -gamma value 
Specifies the gamma correction to apply to the color map for this image. 
The value specified must be greater than zero. The default value is 1 (no 
correction). In general, values greater than : make the image lighter, and 
values less than 1 make it darker. 

® -height number 


Specifies the height of the image, in pixels. A value of o (the default) allows 
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the image to expand or shrink vertically to fit the data stored in it. 

© -palette paletteSpec 
Specifies the color palette to use for this image. The paiertespec string may 
be a single decimal number specifying the number of shades of gray to use, 
for a monochrome image. Or the paiettespec may be three decimal numbers 
separated by slashes (/), specifying the number of shades of red, green, and 
blue to use, respectively, for a color image. 


-width number 
Specifies the width of the image, in pixels. A value of o (the default) allows 
the image to expand or shrink horizontally to fit the data stored in it. 
The image command returned supports a number of subcommands. For those 
commands that write data to the image, the image size can be adjusted as 
necessary, unless the -wiatn and -neignt options have been configured with 
nonzero values. Several of the subcommands accept additional options. 
Some of the options are discussed in the examples that follow; read the 
reference documentation for a complete description. 

° imageName blank 
Erases the image, making it entirely transparent. 

° imageName cget option 
Returns the current value of the configuration option given by option. 

° imageName configure ?option? ?value option value ...? 
Queries or modifies the configuration options for the image. 

° imageName copy sourceImage ?o0ption value ...? 
Copies a region from sourcermage tO imagename. You can optionally specify 
rectangular subregions of the source and/or destination image, as well as 
optionally cropping, subsampling, or zooming, and whether the source 
image replaces or overlays the destination. 

° imageName data ?option value ...? 
Returns image data in the form of a string. You can optionally specify a 
rectangular subregion of the image to return, the data format, whether 
transparent pixels are replaced with a color, and whether to transform the 
data into grayscale. 

© imageName get x y 
Returns the color of the pixel at coordinates x,y, in the image as a list of three 
integers between 0 and 255, representing the red, green, and blue 
components respectively. 

° imageName put data ?option value ...? 
Sets pixels 1n imagename to the data specified in cata. You can optionally 
specify a rectangular subregion for the target data and the image format of 
the data string. The data can also be specified as a Tcl list of scan lines, 
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with each scan line consisting of a list of pixel colors. 


imageName read fileName ?option value ...? 
Reads image data from the file named fitewame into the image. You can 
optionally specify rectangular subregions of the source and/or destination 
image, as well as whether imagename 18 cropped to fit the data read. 

° imageName redither 
Recalculates the dithered image in each window where the image is 
displayed. 

° imageName transparency get x y 
Returns a Boolean indicating whether the pixel at «,) is transparent. 

° imageName transparency set x y boolean 
Makes the pixel at x,y transparent if boolean is true and makes that pixel 
Opaque otherwise. 


imageName write fileName ?option value ...? 

Writes image data from imagewame to a file named fitename. You can optionally 
specify a rectangular subregion of the image to return, the data format, 
whether transparent pixels are replaced with a color, and whether to 
transform the data into grayscale. 

The following examples demonstrate how photo images can be loaded and 
manipulated with the image command using the Tcl Powered logo, a handy 
sample image found in the Tk library. 

The first script reads the Tcl Powered logo image and displays it in a label. 
The result is shown in Figure 20.2. 


Figure 20.2 The Tcl Powered logo image 
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# Fetch and display a source image 
set img [image create photo \ 
-file $tk_library/images/pwrdLogo200.gif] 
label .img -image $img -anchor nw 
grid .img -sticky nw 


The second script creates a new image in which the Tcl Powered logo is 
rotated 90 degrees. It starts by creating an empty image object. The data 
from the original image is then read a pixel at a time with the ger 
subcommand. The return value is a three-element list of the red, green, and 
blue color values for the pixels, ranging from 0 to 255. This is converted 
into a standard ¢recces color string and written to the appropriate pixels in 
the new image using the pur subcommand. To handle transparency properly, 
the transparency setting of the original pixel is tested and replicated on the 
target image if necessary. The result 1s shown in Figure 20.3. 


# Rotate image 90 degrees clockwise 

set imgl [image create photo] 

toplevel .outl 

label .outl.img -image $imgl -anchor mw \ 
-height [image width $img] \ 
-width [image height $img] 

grid .outl.img -sticky nw 


set wid [image width $img] 
set hgt [image height $img] 
for {set x 0} {$x < $wid} {iner x} { 
for {set y 0} {$y < $hgt} {incr y} { 
set color [Simg get $x Sy] 
set rgb [format {#%02x%02x%02x} {*}$color] 
$imgl put $rgb -to [expr {$hgt - $y}] $x 
if {{$img transparency get $x $y]} { 
$imgl transparency set [expr {Shot - $y}] $x 1 
} 
} 
} 


Figure 20.3 The image rotated clockwise 90 degrees 


472 


The third script creates a new image that is reduced to half the size of the 
original. It does so by creating a new empty image object, then it uses the 
copy SUbcommand to copy the image data from the original to the new image. 
The -subsampie Option accepts two additional arguments indicating that the 
copy should use only every «th and yth pixel in the x- and y-coordinates, 
respectively. By setting these values to 2 and 2, only every other pixel in the 
x and y directions is copied. The result is shown in Figure 20.4. Although 
this is fast, it can result in blocky-looking images. A better-looking result 
usually is achieved by averaging pixel values, as 1s shown next. 


# Create half size image by subsampling 
set img2 [image create photo] 

toplevel .out2 

label .out2.img -image $img2 -anchor nw 
grid .out2.img -sticky nw 

$img2 copy $img -subsample 2 2 


Figure 20.4 The image reduced to half size using subsample copying 


The last script also creates a new half-size image. In this case, it does so by 
reading four-pixel blocks using the get subcommand, averaging the color 
values, and writing the result to the target image. If three or four of the 
pixels are transparent, the result is set to transparent. The result is shown in 
Figure 20.5. This averaging technique usually produces a better-looking 
result than subsampling, but it takes substantially longer to process. 
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# Create half-size image 

# by averaging 4-pixel blocks 

set img3 [image create photo] 

toplevel .out3 

label .out3.img -image $img3 -anchor nw 
grid .out3.img -sticky nw 


set wid [image width $img] 
set hgt [image height $img] 
for {set y 0} {Sy < ($hgt - 1)} {incr y 2} { 
set dy [expr {$y / 2}] 
for {set x 0} {$x < (Swid - 1)} {iner x 2} { 
set r 0 
set g 0 
set b 0 
set n 0 
for {set i 0} {$i < 2} {incr i} { 
set xi [expr {$x+$i}] 
for {set j 0} {$j < 2} {iner 3} { 
set yj [expr {$y+$j}] 
if {($img transparency get $xi Syj]} { 
continue 


} 


incr n 
set cx [Simg get $xi $yj] 
incr r [lindex $cx 0] 
incr g [lindex $cx 1] 
incr b [lindex $cx 2] 
} 
} 
set dx lexpr {$x / 2}] 
if {$n < 2} { 
Simg3 put "#000000" -to Sdx $dy 
$img3 transparency set $dx $dy 1 
} else { 
set r [expr {$r / $n}] 
set g [expr {$q / $n}] 
set b [expr {$b / $n}] 
set color [format "#%02x%02x%02x" Sr $qg $b] 
$img3 put Scolor -to $dx S$dy 


Figure 20.5 The image reduced to half size using pixel averaging 
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Tk has a C language interface to the image command that can be used to 
implement support for other image file types. The Img package does just 
that, providing support for BMP, ICO, JPEG, PCX, PNG, PPM, PS, SGI, 
SUN, TGA, TIFF, XBM, and XPM file types. This extension also has an 
option to capture any Tk window as an image. 

Another extension is the TkMagick/TclMagick package that supports 
approximately 100 types. It also provides extensive image manipulation 
capabilities, which can be used in Tcl without Tk. This facilitates image 
manipulation in server-side applications. 

The examples in this section simply illustrate how the image commands work. 
Transformations like the one shown in Figure 20.5 can be performed more 
efficiently with an extension like teimagick. The basic Tk image command 
simply provides a standardized interface to extensions like Img and 
TkMagick so that complex image manipulation can be controlled easily 
from Tcl and the results displayed using Tk. 


20.3.3 Images and Namespaces 


Because creating image objects also creates image commands with the same 
name, you must be careful not to overwrite existing command names. One 
solution is to let image create automatically name the images, in which case 
they'll have names like imageo, imagei, and so on. By default, all image 
commands are created in the global namespace. 

Another strategy is to create a separate namespace for your image names, 
such as ::img, and then create your images with fully qualified namespace 
names, such aS ::img::1ogo and ::img::1arge. With this technique, any images 
associated with a particular module or library could also be created within 
the library’s namespace. See Chapter _10 for more information on 
namespaces. 


Note 
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For this technique to work, you should always use fully qualified 
namespace references for your image names, such as ::img::1ogo, not 
partially qualified references like img::1ogo. The image command is 
created relative to the current namespace, so if you are not in the 
global namespace when you create the image and you use a partially 
qualified reference for the image name, the name of the image 
command does not match the name of the image itself. 
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21. Geometry Managers 


Geometry managers determine the sizes and locations of widgets. Tk is 
similar to other toolkits in that it does not allow widgets to determine their 
own geometries. A widget does not even appear on the screen unless it is 
managed by a geometry manager. This separation of geometry management 
from internal widget behavior allows multiple geometry managers to exist 
simultaneously and permits any widget to be used with any geometry 
manager. If widgets controlled their own geometry, this flexibility would be 
lost: every existing widget would need to be modified to introduce a new 
style of layout. 

This chapter describes the overall structure of geometry management and 
then presents the three geometry managers. The gridder, which is the most 
commonly used geometry manager in Tk, allows you to arrange widgets into 
rows and columns. The packer arranges widgets around the edges of an 
area. The placer provides simple fixed and “rubber sheet” placement of 
widgets. There are also several widget classes that can act as geometry 
managers: canvas and text, which are discussed in Chapter 23 and Chapter 24 
respectively; paneawindow (and its themed counterpart, ttk::paneawindow), Which 
is described in Chapter 18; and ttk::notebook, Which is described in Chapter 
Le: 


21.1 Commands Presented in This Chapter 


All geometry managers have a common set of subcommands, as well as a 
set of unique features. The following are the subcommands they have in 
common, where om 1s one Of piace, pack, OF grid! 

© gm slave ?slave ...? option value ?0ption value ...? 
Same as the configure Subcommand described below, unless you are querying 
geometry manager options. 

® gm configure slave ?slave ...? ?option? 

?value option value ...? 

Arranges for the geometry manager to manage the geometry of the widgets 
named by the siave arguments. The option and vaiue arguments provide 
information that determines the dimensions and positions of the slaves. 


° om forget slave ?slave ...? 
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Causes the geometry manager to stop managing the widgets named by the 
slave arguments and unmap them from the screen. Has no effect if siave isn’t 
currently managed by this geometry manager. 

® gm info slave 
Returns a list giving the current configuration of siave. The list consists of 
option-value pairs in exactly the same form as might be specified to the 
geometry manager’s configure command. Returns an empty string if siave isn’t 
currently managed by this geometry manager. 

° gm slaves master ?0ption value? 
Returns a list of the slaves on master’s list for this geometry manager. 
This chapter also discusses the following commands for managing the 
stacking order of widgets: 

*° lower widget ?belowThis? 
Changes wiaget’s position in the stacking order so that it is just below the 
widget given by nelowrnis. If be1owrnis 18 omitted, it MOVES widget to the bottom 
of the stacking order. 

© raise widget ?aboveThis? 
Changes wiaget’s position in the stacking order so that it is just above the 
widget given by abovernis. If abovernis 18 omitted, 1t MOVES wiager to the top of 
the stacking order. 


21.2 An Overview of Geometry Management 


A geometry manager’s job is to arrange one or more s/ave widgets relative 
to a master widget. For example, it might arrange three slaves in a row from 
left to right across the area of the master, or it might arrange two slaves so 
that they split the space of the master, with one slave occupying the top half 
and the other occupying the bottom half. Different geometry managers 
embody different styles of layout. The master is usually the parent of the 
slave, but there are times when it’s convenient to use other windows as 
masters (you will see examples of this later). 

Masters are usually frame or toplevel widgets but can be any widget. A 
master is used to define the geometric bounds for the slave widgets only, 
and the widgets’ contents are otherwise unaffected. The slave widgets 
normally appear on top of the master but can be arranged to be underneath if 
necessary. This stacking order is defined by the order in which the widgets 
are created (this is discussed more in Section 21.8). 

A geometry manager receives three pieces of information for use in 
computing a layout (see Figure 21.1). First, each slave widget requests a 
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particular width and height. These are usually the minimum dimensions the 
widget needs to display its information. For example, a button widget 
typically requests a size just large enough to display its text or image. 
Although geometry managers aren’t obliged to satisfy the requests made by 
their slave widgets, they usually do. 


Figure 21.1 A geometry manager determines the size and placement of slave 
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Sizes and locations Requested sizes 
of slaves for master 


The second kind of input for a geometry manager comes from the 
application designer and is used to control the layout algorithm. The nature 
of this information varies from geometry manager to geometry manager. For 
example, the gridder arranges slave widgets in rows and columns, so row 
and column numbers are needed to identify where to position the widgets. 
The third piece of information used by geometry managers is the geometry 
of the master window. For example, the geometry manager might position a 
slave at the lower left corner of its master, or it might divide the space of 
the master among one or more slaves, or it might refuse to display a slave 
altogether if it doesn’t fit within the area of its master. 

After it has received all of the preceding information, the geometry manager 
executes a layout algorithm to determine the width, height, and position of 
each of its slaves. If the geometry manager assigns a slave a size different 
from what it requested, the widget must make do in the best way it can. 
Geometry managers usually try to give widgets the space they request, but 
they may produce more attractive layouts by giving widgets extra space in 
some situations. If there isn’t enough space in a master for all of its slaves, 
some of the slaves may get less space than they requested. In extreme cases 
the geometry manager may choose not to display some slaves at all. 
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The controlling information for geometry management may change while an 
application runs. For example, a button might be reconfigured with a 
different font or bitmap, in which case it changes its requested dimensions. 
In addition, the geometry manager might be told to use a different approach 
(for example, arrange a collection of windows from top to bottom instead of 
left to right), some of the slave windows might be deleted, or the user might 
interactively resize the master window. When any of these things happens, 
the geometry manager recomputes the layout. 

Some geometry managers set the requested size for the master window. For 
example, the gridder computes how much space is needed in the master to 
accommodate all of its slaves in the fashion requested by the application 
designer. It then sets the requested size for the master to these dimensions, 
overriding any request made by the master widget itself. This approach 
allows for hierarchical geometry management, where each master is itself 
the slave of another higher-level master. Size requests pass up through the 
hierarchy from each slave to its master, resulting ultimately in a size request 
for a toplevel window, which is passed to the window manager. Then actual 
geometry information passes down through the hierarchy, and the geometry 
manager at each level uses the geometry of a master to compute the 
geometry of one or more slaves. As a result, the entire hierarchy sizes itself 
to meet the needs of the lowest-level slaves; the overall effect is that the 
master widgets “shrink-wrap” around their slaves. 

Each widget can be managed by at most one geometry manager at a time, 
although it is possible to switch geometry managers during the life of a 
slave. A widget can act as a master to any number of slaves, and a single 
geometry manager can simultaneously manage different groups of slaves 
associated with different masters. Although it is possible for different 
geometry managers to control different groups of slaves within the same 
master, it is not recommended. 

Only internal widgets may be slaves for geometry management. The 
techniques described here do not apply to toplevel widgets since they are 
managed by the window manager for the display. See Chapter 26 for 
information on how to control the geometry of toplevel widgets. 


21.3 The Gridder 


The gridder is a straightforward geometry manager that arranges slaves into 
rows and columns and allows them to span multiple rows and columns. 
Most application layout needs can be satisfied with the gridder options 


481 


without resorting to additional frames and hierarchical layout techniques 
(see Section 21.7). 
Each slave for a given master is assigned a row and column location, or 
cell, in the grid. The gridder shrink-wraps each column to the width of the 
largest slave in the column and correspondingly shrink-wraps each row to 
the height of the largest slave in the row, as shown in Figure 21.2. This is 
done in three steps: 
1. The minimum size is determined for each row and column that 
accommodates all the slaves based on each slave’s requested size. 
This minimum size then becomes the requested size for the master. 
2. The actual size of the master 1s compared with this requested size, 
and then space is added to or removed from the layout as needed. 
3. Each slave is positioned within its cell according to its 
configuration flags. 


Figure 21.2 The gridder geometry manager arranges slave widgets into 
rows and columns. 


Master Slaves 
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The gridder geometry manager arranges slave widgets into rows and 
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columns, as shown in Figure 21.2(a). Slaves can also span rows or columns 
to occupy more than one cell, as shown in Figure 21.2(b). The rows and 
columns “shrink-wrap” around the widgets so that the master is only as 
large as it needs to be to accommodate all the slaves, as illustrated in Figure 
21 2tG). 

The gria configure command (the word configure 18 optional, unless you are 
querying grid options) adds one or more widgets to grid control or changes 
the gridding options of widgets already under grid control: 


grid slave ?slave ...? option value ?Poption value ...? 
grid configure slave ?slave ...? ?Poption? \ 
?value option value ...? 


There are a number of different configuration options for the gridder that 
control slave placement, stretching behavior, cell size, and grid size: 


® -column n 


Inserts the slave into the rth column. 
* -columnspan n 
Inserts the slave so that it occupies » columns (see Section 21.3.3). 


® -in master 


Use master as the master for the slave. master must be the slave’s parent or a 
descendant of the slave’s parent. If this option is not specified, the master 
defaults to the slave’s parent. 

® -ipadx distance 
Adds internal horizontal padding between the widget’s border and its 
content, expressed as a screen distance. 

© -ipady distance 
Adds internal vertical padding between the widget’s border and its content, 
expressed as a screen distance. 

® -padx distance 
Adds external horizontal padding around the widget, expressed as a screen 
distance; a two-element list can be provided to specify left and right 
padding independently (see Section 21.5). 

© -pady distance 
Adds external vertical padding around the widget, expressed as a screen 
distance; a two-element list can be provided to specify top and bottom 
padding independently (see Section 21.5). 


® -row n 


Inserts the slave into the »th row. 
° -rowspan n 


Inserts the slave so that it occupies » rows (see Section 21.3.3). 
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® -sticky style 
Controls the position and stretching of a slave if a slave’s cell is larger than 
its requested dimensions (see Section 21.3.1). 
The gridder also supports columnconfigure aNd rowconfigure SUbcommands for 
setting and querying the configuration of columns and rows in the master: 


grid columnconfigure master index ?option? ?option? \ 
?value option value ...? 

grid rowconfigure master index ?Poption? Poption? \ 
?value option value ...? 


If one or more options are provided, inaex may be given as a list of column 
indices to which the configuration options apply. Indices may be integers, 
names of widgets in the grid, or the keyword aii. Currently supported 
options are 


® -minsize amount 


The minimum size for a column/row, expressed as a screen distance. 

© -pad amount 
Adds external padding around each widget in the column/row, expressed as 
a screen distance. 

° -weight int 
The relative weight for apportioning any extra space among columns when 
resizing (see Section 21.3.3). 


® -uniform groupName 


Symbolic name of a group of columns/rows whose resizing is proportionate 
(see Section 21.3.3). 


21.3.1 The gria Command and the -sticky Options 


The gria command is used to communicate with the gridder. In its simplest 
form the command takes a list of slaves and options and places each slave 
in a subsequent column starting with o. Each subsequent gria command for 
the same master starts a new row. The -row and -coiumn options can be used to 
provide a specific cell or starting point. 

If a slave does not entirely fill its cell, it is positioned in the center of its 
cell by default. The -sticky option is used to anchor or stretch a slave to any 
side or direction. This option takes any one or more of the characters 1, s, e«, 
or w. Each character causes the slave to stick to the corresponding side of 
the cell; if opposite sides are given, the slave is stretched between those 
two sides. 
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The following code demonstrates the effects of different -sticxy options 
using a label widget surrounded by four checkbuttons in a 3-by-3 grid. 
Notice also that some cells, the four corners in this example, may be empty. 
In this case the master widget shows through. Figure 21.3 shows some 
examples from this application: 


Figure 21.3 The label in the center demonstrates different -sticxy options. 
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label .demo -textvariable stickyLabel -bd 2 -relief raised 

checkbutton .n -text "n" -bd 2 -relief raised \ 
-variable stickyN -onvalue n -offvalue {} \ 
-command redo_sticky 

checkbutton .s -text "s" -bd 2 -relief raised \ 
-variable stickyS -onvalue s -offvalue {} \ 
-command redo_sticky 

checkbutton .e -text "e" -bd 2 -relief raised \ 
-variable stickyE -onvalue e -offvalue {} \ 
-command redo sticky 

checkbutton .w -text "w" -bd 2 -relief raised \ 
-variable stickyW -onvalue w -offvalue {} \ 
-command redo sticky 


grid .demo -row 1 -colum 1 

grid .n -row 0 -column 1 -sticky nsew 
grid .s -row 2 -column 1 -sticky nsew 
grid .e -row 1 -column 2 -sticky nsew 
grid .w -row 1 -column 0 -sticky nsew 


grid rowconfigure . 1 -weight 1 
grid columnconfigure . 1 -weight 1 


wm geometry . 180x100 


proc redo sticky {} { 
global stickyN stickyS stickyE stickyW stickyLabel 


append s2 $stickyN $stickyS $stickyE $stickyw 
grid .demo -row 1 -column 1 -sticky $s2 
set stickyLabel [list -sticky $s2] 


21.3.2 Spanning Rows and Columns 


A gridded widget can span multiple rows or columns. In the following code, 
the -columnspan option causes the .1ape1 widget to use both columns in the first 
row. This area is then treated as a single cell, as shown in Figure 21.4. 
Likewise, the -rowspan option can be used to span multiple rows. 


grid .label -columnspan 2 

grid .listbox -sticky nsew 

grid .scrollbar -row 1 -column 1 -sticky ns 
grid .xscrollbar -sticky ew 
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Figure 21.4 A label spanning multiple columns 
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When the gridder computes the minimum master size, it first looks at all the 
slaves with a row and column span of 1. Then the slaves with row and 
column spans greater then 1 are examined, and if additional space is needed, 
the space is distributed across the spanned rows or columns. 


21.3.3 Stretch Behavior and the -weight and -uniform Options 


When a master window has more space than the slaves need, such as when a 
user interactively stretches a window, the gridder must allocate this extra 
space somewhere. There are several options that can control how the space 
is distributed. For example, in Figure 21.4 the desired behavior is for all 
additional space to be first given to the listbox widget, and then have the 
scrollbars stretch as needed. This can be accomplished easily by weighting 
the cell that the .1:stbox widget occupies, column 0 and row 1, with a higher 
weight than the others, as shown in Figure 21.5. Weights are assigned to 
rows and columns using the -weight option to the gria rowconfigure and gria 
columnconfigure Commands. With the default weight of o, when the window 
shown in Figure 21.5(a) is resized as in Figure 21.5(b), the widgets do not 
expand to fill the space. When a weight of 1 is assigned to row 1, the rows 
expands to fill the space, as shown in Figure 21.5(c), and assigning a weight 
of 1 to column 0 expands the column to complete the expansion, shown in 


Figure 21.5(d). 


Figure 21.5 Effect of using weighted rows and columns with the gridder 
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By default the gridder assigns a weight of o to all rows and columns. No 
additional space is allocated to rows or columns witha weight of o. Weights 
higher than o are allocated additional space proportionally, with -weignt 2 
getting twice as much space as -weignt 1. 

The -uniform option is used to group rows and columns with similar weights. 
This way a set of rows or columns can be configured to always have the 
same size. For example, multiple rows configured with -weignt 1 -uniform a 
all have the same height. See the reference documentation for more 
information. 


21.3.4 Relative Placement Characters 


The gria command provides a shorthand notation for placing slaves without 
having to specify explicit row and column numbers. By default, each slave 
specified in a gria command is placed in subsequent columns, and each new 
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gria Command starts a new row. This creates an organization in the source 
code that represents the layout on the screen. 

There are three relative placement characters that can be used where a slave 
would normally appear in the gria command: -, x, and ~. The - character 
extends the previous slave into the next column, and each subsequent - 
character continues to increase the column span for the slave. The « 
character leaves the cell blank. The ~« character extends the slave in the 
previous row down into the current cell, and each ~ in subsequent gria 
commands continues to increase the row span for the slave. Figure 21.6 
demonstrates the use of each of these relative placement characters using the 
following code: 


ttk::label .wl -text "Label 1" -relief raised 
ttk::label .w2 -text "Label 2" -relief raised 
ttk::label .w3 -text "Label 3" -relief raised 
ttk::label .w4 -text "No.\n4" -relief raised 
ttk::label .w5 -text "No.\n5" -relief raised 
grid wl - x .w4 -sticky nsew 

grid -w5 .w2 . -sticky nsew 


grid x .w3 - -sticky nsew 


Figure 21.6 Relative placement characters can simplify grid layout 
commands. 


Label! No. 


No, Label 2) 4 
5 Label 3 


21.4 The Packer 


The packer arranges the slaves for a master by positioning them one at a 
time in the master’s window, working from the edges toward the center. The 
packer is easy to use in simple cases where a single row or column is 
needed, but it is also capable of complex layouts. Although you can achieve 
any arrangement of widgets with either the packer or the gridder, complex 
layouts are usually easier to create with the gridder. 

The packer maintains a list of slaves for a given master window, called the 


489 


packing list. The packer arranges the slaves by processing the packing list 
in order, packing one slave in each step. At the time a particular slave is 
processed, part of the area of the master window has already been allocated 
to earlier slaves on the list, leaving a rectangular unallocated area for all the 
remaining slaves, called the cavity, as shown in Figure 21.7(a). The current 
slave is positioned in three steps: allocate a parcel, stretch the slave, and 
position it in the parcel. 


Figure 21.7 The packer arranges slaves around the edges of the master. 


Master Slave 
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In the first step a rectangular region called a parcel, or packing space, is 
allocated from the available space. This is done by “slicing” off a piece 
along one side of the available space. For example, in Figure 21.7(b) a 
parcel is sliced from the right side of the available space. One dimension of 
the parcel is determined by the size of the available space, and the other 
dimension is controllable. The controllable dimension is normally taken 
from the slave’s requested size in that dimension, but the packer allows you 
to request additional space if you wish. In Figure 21.7(b) the width is the 
controllable dimension; if the parcel had been sliced from the top or bottom, 
the parcel’s height would have been controllable instead of its width. 

In the second step the packer chooses the dimensions of the slave. By 
default the slave gets the size it requested, but you can specify instead that it 
should be stretched in one or both dimensions to fill the space of the parcel. 
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If the slave’s requested size is larger than the parcel, it is reduced to fit the 
size of the parcel. 

The third step is to position the slave inside its parcel. If the slave is 
smaller than the parcel, an anchor position may be given for the slave, such 
aS n, s, OF center. In Figure 21.7(c) the slave has been positioned in the center 
of the parcel, which is the default. 

Once the slave has been positioned, a smaller rectangular region is left for 
the next slave to use, as shown in Figure 21.7(d). If a slave doesn’t use all 
of the space in its parcel, as in Figure 21.7, the leftover space is not used 
for later slaves. Thus each step in the packing starts with a rectangular 
region of available space and ends up with a smaller rectangular region. 
Once all of the slaves have been packed, the packer then sizes the master 
widget to meet the needs of the lowest-level slaves, with the overall effect 
that the master widget “shrink-wraps” around its slaves. 

The pack configure command (the word configure 18 optional, unless you are 
querying packer options) adds one or more widgets to packer control or 
changes the packing options of widgets already under packer control: 


pack slave ?slave ...? option value ?option value ...? 
pack configure slave ?slave ...? ?option? \ 
?value option value ...? 


There are a number of different configuration options for the packer that 
control slave characteristics such as placement, stretching behavior, cell 
size, and positioning: 

© -after widget 
Use wiaget’S master as the master for the slave, and insert the slave into the 
packing list just after wiager. 

® -anchor position 
Controls the position of a slave if a slave’s cell is larger than its requested 
dimensions (see Section 21.4.4). Defaults to center. 

° -before window 
Use window's master as the master for the slave and insert the slave into the 
packing list just before window. 

®° -expand boolean 
If boolean 18 a true value, the slave’s parcel grows to absorb any extra space 
left over in the master (see Section 21.4.3). Defaults to false. 

® _fill style 
Specifies whether (and how) to grow the slave if its parcel is larger than the 
slave’s requested size (see Section 21.4.2). styie must be either none, x, y, OF 


both. Defaults to none. 
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® -in master 


Use master aS the master for the slave. master must be the slave’s parent or a 
descendant of the slave’s parent. If this option is not specified, the master 
defaults to the slave’s parent. 

® -ipadx distance 
Specifies internal horizontal padding added between the widget’s border 
and its content, expressed as a screen distance. 

® -ipady distance 
Specifies internal vertical padding added between the widget’s border and 
its content, expressed as a screen distance. 

® -padx distance 
Specifies external horizontal padding added around the widget, expressed 
as a screen distance; a two-element list can be provided to specify left and 
right padding independently (see Section 21.5). 

® -pady distance 
Specifies external vertical padding added around the widget, expressed as a 
screen distance; a two-element list can be provided to specify top and 
bottom padding independently (see Section 21.5). 

© -side side 
side Specifies which side of the master the slave should be packed against 
(see Section 21.4.1). Must be top, bottom, 1eft, OF rignt. Defaults to top. 


21.4.1 The pack Command and -side Options 


The pack command is used to communicate with the packer. In its simplest 
form it takes one or more widget names as arguments, followed by one or 
more pairs of additional arguments that indicate how to manage the widgets. 
For example, consider the following script, which creates three buttons and 
arranges them in a row: 


ttk::button .ok -text OK 
ttk::button .cancel -text Cancel 
ttk::button .help -text Help 
pack .ok .cancel .help -side left 


The pack command asks the packer to manage .ox, .cancei, and .ne1p aS Slaves 
and to pack them in that order. The master for the slaves defaults to their 
parent, whichis ., the main widget. The option -sice 1ert applies to all three 
of the widgets; it indicates that the parcel for each slave should be allocated 
on the left side of the available space. Because no other options are 
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specified, the parcel for each slave is allocated to be just large enough for 
the slave. This causes the slaves to be arranged in a row from left to right 
across the master. Furthermore, the packer computes the minimum size 
needed by the master to accommodate all of its slaves, and it sets the 
master’s requested size to these dimensions. The window manager sets the 
main widget’s size as requested, so the master ends up shrink-wrapped 
around the slaves, as shown in Figure 21.8(a). 


Figure 21.8 Simple packer examples 


G-)ox) REESE 015) | cance! Command 


Ok Cancel Help Ok Cancel Command Help | Help | 
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The packer recomputes the layout whenever any of the relevant information 
changes. For example, if you type the command 


.cancel configure -text "Cancel Command" 


to change the text in the middle button, the button changes its requested size 
and the packer changes the layout to make more space for it, as in Figure 
21.8(b). If you then type the command 


pack .ok .cancel -help -side top 


the layout changes so that each slave is allocated at the top of the remaining 
space, producing the columnar arrangement shown in Figure 21.8(c). In this 
case, the master’s width is chosen to accommodate the largest of the slaves 
(.cance1). Each of the other slaves receives a parcel wider than it needs, and 
the slave is centered in its parcel. 


21.4.2 Filling 


If a parcel ends up larger than the size its slave requested, you can use the - 
fi11 option to stretch the slave so that it fills the parcel in one or both 
directions. For example, consider the column of widgets in Figure 21.8(c): 
each widget is given its requested size, which results in a somewhat ragged 
look because the buttons are all different sizes. The -<i11 option can be used 
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to make all the buttons the same size: 


pack .ok .cancel .help -side top -fill x 


Figure 21.9 shows the effect produced by this command: each of the slaves 
is stretched horizontally to fill its parcel, and since the parcels are as wide 
as the master window, all of the slaves end up with the same width. 


Figure 21.9 The effect of using -+i11 


Cancel Command 


Help 


Figure 21.10 shows another simple example of filling. The three windows 
are configured differently, so a separate pack command is used for each one. 
The order of the pack commands determines the order of the windows in the 
packing list: 


pack .label -side top -fill x 
pack .scrollbar -side right -fill y 
pack .listbox 


Figure 21.10 Another packer example using the -<:11 and -siae options 


oe 
Bees List of States: 


(s)(allx) 
List of States: 


New Jersey ‘New Jersey 

New York New York 

‘New Hampshire ‘New Hampshire 

‘North Carolina \North Carolina 
= | North Dakota ve ‘North Dakota 
= | Ohio = ‘Ohio 

Oklahoma ‘Oklahoma 

Pennsylvania —— 

Puerto Rico Puerto Rico 


6 ©) 


The .iabe1 widget is packed first, and it occupies the top part of the master 
window. The -+i11 x option specifies that the window should be stretched 
horizontally so that it fills its parcel. The scrollbar widget is packed next, in 
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a similar fashion except that it is arranged against the right side of the 
window and stretched vertically. The widget .iistnox 1s packed last. No 
options need to be specified for it: it ends up in the same place regardless of 
which side it is packed against. 

Without the -si11 option, the label and scrollbar would simply occupy the 
center of the parcel, as Figure 21.10(b) illustrates. Adding -+i11 causes them 
to stretch and occupy the full parcel, as seen in Figure 21.10(c). 


21.4.3 Expansion 


Sometimes a master window has more space than its slaves need. This can 
occur, for example, if a user interactively stretches a window. When this 
happens, the default behavior of the packer is to leave the extra space 
unused, as in Figure 21.11(a). However, you can use the -expana option to tell 
the packer to give any extra space to a particular slave (for example, expand 
a text widget to fill all the extra space), or to divide the extra space 
uniformly among a collection of slaves (for example, distribute a collection 
of buttons uniformly across the available space). The -expana option makes it 
possible to produce layouts that are attractive regardless of how the user 
resizes the window, so that the user can choose the size he or she prefers. In 
each of the examples in Figure 21.11, the size of the main widget was fixed 
with the command wm geometry . 232x62 to simulate what would happen if the 
user had interactively resized the window. 


Figure 21.11 Examples of using -expana and -£111 
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| First, Second , Third , Extra , | First , Second , Third 
(8) \parcel, parcel , parcel, space (b) jparcel, parcel , parcel: ; 
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pack .ck .cancel -help \ pack .ok .cancel -side left 
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Figure 21.11 shows how -expana works. If you specify -expana for a slave, as 
with .neip in Figure 21.11(b), the slave’s parcel expands to include any extra 
space in the master. In Figure 21.11(b), -<i11 x has also been specified for 
help, SO the slave window is stretched to cover the entire width of the 
parcel. Figure 21.11(c) is similar to Figure 21.11(b) except that no filling is 
specified, So .neip 18 simply centered in its parcel. 

If you specify -expana for multiple slaves, their parcels share the extra space 
equally. Figure 21.11(d) shows what happens if all of the windows are 
packed with -expand but no filling, and Figure 21.11(e) shows what happens 
when the slaves are also filled in both dimensions. 


Note 


The options -expana and -ri11 are often confused because of the 
similarity of their names. The -expana option determines whether a 
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parcel absorbs extra space in the master, and -+i11 determines whether 
a Slave’s window absorbs extra space in its parcel. The options are 
often used together so that a slave’s window absorbs all the extra 
space in its master. 


21.4.4 Anchors 


If a parcel has more space than its slave requested (for example, because 
you specified -expana for it), and if you choose not to stretch the slave with 
the -si11 option, the packer normally centers the slave in its parcel. The - 
anchor Option allows you to request a different position: its value specifies 
where the slave should be positioned in the parcel, in one of the forms listed 
in Section 18.15.3. For example, -anchor nw specifies that the slave should be 
positioned in the upper left corner of its parcel. Figure 21.12(a) shows how 
-anchor can be used to left-justify a collection of buttons. 


Figure 21.12 Examples of the -anchor option 


pack .ok .cancel .help -side left 


Ix] pack .ok .cancel -side left 
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The -<i11 and -anchor options preserve external padding requested with -paax 
and -paay. For example, Figure 21.12(b) is the same as Figure 21.12(a) 
except that external padding has been requested. In this case the buttons 
aren’t positioned at the left edges of their parcels, but instead they are inset 
by the -paax distance. 


21.4.5 Packing Order 
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The -vefore and -arter options allow you to control a slave’s position in the 
packing list for its master. If you don’t specify one of these options, each 
new slave goes at the end of the packing list. If you specify -berore or -arfter, 
its value must be the name of a window that is already packed, and the new 
slave(s) are positioned just before or after the given slave, respectively. 


21.5 Padding 


Both the packer and the gridder provide four options for requesting extra 
space for a slave. The extra space is called padding, and it comes in two 
forms: external padding and internal padding. External padding is 
requested with the -paax and -paay options; these options cause the packer to 
allocate a parcel larger than that requested by the slave and leave extra 
space around the outside of the slave. For example, the widgets in Figure 
21.13(a) are packed with the options 


-padx 2m -pady Im 
Figure 21.13 Examples of padding 


(a) DICE: 
Ok Cancel | Help 


grid .ok .cancel .help -padx 2m -pady 1m 


grid .ok .cancel .help -ipadx 2m -ipady 1m 


Ok Cancel Help 


7  — 


grid .ok .cancel .help -padx 2m -pady 1m \ 
-ipadx 2m ipady lm 


These options specify that there should be 2 millimeters of extra space on 
each side of each of the widgets and 1 millimeter of extra space above and 
below each widget. Internal padding is requested with the -ipaax and -ipaay 
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options; they also cause a parcel to be larger than what the slave requested, 
but in this case the slave window is enlarged to incorporate the extra space, 
as in Figure 21.13(b). External and internal padding can be used together, as 
in Figure 21.13(c), and different slaves can have different amounts of 
padding. 


21.6 The Placer 


The placer is the most simplistic geometry manager and is used typically in 
specialized applications. Slave widgets are placed by the manager 
precisely where specified by the piace command options; there are no 
special algorithms applied to the layout. It is simplistic because it does very 
little work, putting the onus on the application to manage the layout. The 
placer should be used only in situations where the gridder or packer cannot 
perform the required layout. The placer does provide a relative placement 
option, which gives a “rubber sheet” effect to the slave widgets. Slave 
windows managed by the placer do not affect other slave geometries as is 
the case in other geometry managers, nor is size information propagated to 
the master. 

The piace command is used to communicate with the placer. In its simplest 
form it takes one or more widget names as arguments, followed by one or 
more pairs of additional arguments that indicate how to place the widgets. 
Placement is controlled by an exact location (-x, -y) and by an exact size (- 
width, -height) and is a position within the master window, or relative 
placement may be used where the location (-re1x, -re1y) and $1Ze (-reiwiatnh, - 
relheight) are specified as floating-point numbers relative to the master. For 
the other options available for the placer, see the reference documentation. 


21.7 Hierarchical Geometry Management 


Both the packer and the gridder can be used in hierarchical arrangements 
where slave windows are also masters for other slaves. Figure 21.14 shows 
an example of hierarchical packing. The resulting layout contains a column 
of radiobuttons on the left and a column of checkbuttons on the right, and 
each group of buttons is centered vertically in its column. To achieve this 
effect, two extra frame widgets, .1crt and .rignt, are packed side by side in 
the main window, then the buttons are packed inside them. The packer sets 
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the requested sizes for .1ert and .right to provide enough space for the 
buttons, then uses this information to set the requested size for the main 
widget. The main widget’s geometry is set to the requested size by the 
window manager, then the packer arranges .icrt and .right inside it, and 
finally it arranges the buttons inside .1et and .right. Here is the code that 
produced the layout: 


frame .left 
frame .right 
set buttonList [list] 
foreach size {8 10 12 18 24} { 
ttk::radiobutton .ptsSsize -text "$size points" \ 
~variable pts -value $size 
lappend buttonList .ptsS$size 
} 
ttk::checkbutton .bold -text Bold -variable bold 
ttk::checkbutton .italic -text Italic -variable italic 
ttk::checkbutton .underline -text Underline \ 
-variable underline 
pack {*}$buttonList -in .left -side top -anchor w 
pack ,bold .italic .underline -in .right -side top \ 
-anchor w 
pack .left -side left -padx 3m -pady 3m 
pack .right -side right -padx 3m -pady 3m 


Figure 21.14 An example of hierarchical packing 
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This code also illustrates a situation where a slave’s master is different 
from its parent (by using the -in option to specify a master). It would have 
been possible to create the button windows as children of .icre and .rignt 
(for example, .icrt.ptss instead of .ptss), but it 1s cleaner to create them as 
children of . and then pack them inside .1ert and .right. The windows .1ert 
and .right Serve no purpose in the application except to help in geometry 
management; they have the same background color as the main widget, so 
they are not even visible on the screen. If the buttons were children of their 
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geometry masters, changes to the geometry management (such as adding 
more levels in the packing hierarchy) might require the button windows to 
be renamed and would break any code that used the old names. It is better to 
give windows names that reflect their logical purpose in the application, 
build separate frame hierarchies where needed for geometry management, 
and then pack the functional windows into the frames. 


Note 


In the example in Figure 21.14, the frames .1ert and .rignt must be 
created before the buttons so that the buttons are stacked on top of the 
frames. The most recently created widget is highest in the stacking 
order; if .1ert 18 created after .ptss, it is on top of .ptss, SO .ptss 18 not 
visible. Alternatively, the raise and 1ower commands can be used to 
adjust the stacking order (see Section 21.8). 


A slave’s master must be either its parent or a descendant of its parent. The 
reason for this restriction has to do with the clipping rules in some 
windowing systems. Each window ts clipped to the boundaries of its parent, 
so no portion of a child that lies outside of its parent is displayed. Tk’s 
restriction on master windows guarantees that a slave is visible and 
unclipped if its master is visible and unclipped. Suppose that the restriction 
were not enforced, so that window .«.y could have .a as its master. Suppose 
also that .2 and .x do not overlap at all. If you asked the packer to position 
.x.y IN .a, the packer would set .x.y’s position as requested, but this would 
cause .x.y to be outside the area of .x, so the windowing system would not 
display it even though .a is fully visible. This behavior would be confusing 
to application designers, so Tk restricts mastership to keep the behavior 
from occurring. The restriction applies to all of Tk’s geometry managers. 


21.8 Widget Stacking Order 


Stacking order determines the layering of widgets on the screen. If two 
sibling widgets overlap, the stacking order determines which one appears 
on top of the other. Widgets are normally stacked in the order of their 
creation: each new widget goes at the top of the stacking order, obscuring 
any of its siblings that were created before it. The raise and 1ower commands 
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allow you to change the stacking order of widgets: 


raise .w 
raise .w .xX 
lower .w 


lower .w .x 


The first command raises .w so that it is at the top of the stacking order (it 
obscures all of its siblings). The second places .w just above .x in the 
stacking order. The third command lowers .w to the bottom of the stacking 
order (it is obscured by all of its siblings), and the last command places .w« 
just below .« in the stacking order. 

Most of the time the stacking order 1s not important, since most widgets are 
positioned without overlap. When the piace window manager is used, 
widgets can overlap, and when the -in option is used with any of the 
window managers, the slave widget must be above the master; otherwise the 
slave widget is not visible. 


Note 


You can use raise and tower for toplevel widgets as well as internal 
widgets, but this does not work for all window managers. Some 
window managers prevent applications from raising and lowering their 
toplevel windows; with these window managers you must raise or 
lower toplevel widgets manually using window manager functions. 


21.9 Other Geometry Manager Options 


So far the geometry manager commands have been discussed in their most 
common form, where the first arguments are the names of slave windows 
and the last arguments specify configuration options. Section 21.1 shows 
several other common forms for the geometry manager commands, where 
the first argument selects one of several operations. These commands apply 
to all three geometry managers: gria, pack, and piace. The gria configure 
command, for example, has the same effect as the short form that’s been 
used up until now; the remaining arguments specify windows and 
configuration options. If, for example, gria configure (or the short form with 
no command option) is applied to a window that is already managed by the 
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gridder, the slave’s configuration is modified; configuration options not 
specified in the gria command retain their old values. 

The command option saves returns a list of all of the slaves for a given 
master window. For the packer, the order of the slaves reflects their order in 
the packing list: 


pack slaves left 
=.ptsS .ptsl0 .ptsl2 .pts18 .pts24 


The command option ino returns all of the configuration options for a given 
slave: 


pack info .pts8 
=> -in .left -anchor w -expand 0 -fill none -ipadx 0?-ipady 0 


-padx 0 -pady 0 -side top 


The return value is a list consisting of names and values for configuration 
options 1n exactly the form in which you would specify them to pack configure. 
This command can be used to save the state of a slave so that it can be 
restored later. 

The command option forget causes the geometry manager to stop managing 
one or more slaves and forget all of its configuration state for them. It also 
unmaps the windows so that they no longer appear on the screen. This 
command can be used to transfer control of a window from one geometry 
manager to another, or simply to remove a window from the screen. If a 
forgotten window is itself a master for other slaves, the information about 
those slaves is retained, but the slaves won’t be displayed on the screen 
until the master window becomes managed again. 


Note 


The gridder is unique in having a remove command option. It removes 
slaves from the grid and unmaps their windows, just like the forget 
command option. However, the configuration options for that window 
are remembered, so that if the slave is managed once more by the 
gridder, the previous values are retained. 


The command option propagate allows you to control whether or not the 
packer or gridder sets the requested size for a master window. Normally 
these geometry managers set the requested size for each master window to 
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just accommodate the needs of its slaves, and it updates the requested size 
as the needs of the slaves change. This feature is called geometry 
propagation, and it overrides any size that the master might have requested 
for itself. You can disable propagation with one of the following commands, 
depending on which geometry manager is controlling the layout of the 
master: 


pack propagate master 0 
grid propagate master 0 


where master 1S the name of the master window. This instructs Tk not to set 
the requested size for master, so that the size requested by the master widget 
itself is used. You can resume propagation by providing a value of 1 to the 
command instead of o. 

Each geometry manager has additional options unique to its algorithm. See 
the reference documentation for a complete listing. 


21.10 Other Geometry Managers in Tk 


As mentioned earlier, there are Tk widgets that can act as geometry 
managers; that is, they can map widgets onto the display and control their 
size and placement. The text widget is capable of embedding windows into 
a text document where each window is treated like a font glyph. The 
requested size of the window becomes the glyph size, and the text widget 
maps the window accordingly. The canvas widget can also embed windows 
and map them to the display. It does this according to its own method of 
placing objects onto the canvas. You can find out more information about the 
canvas and text widgets in Chapter 23 and Chapter 24, respectively. 

The panedwindow (and its themed counterpart, ttk::panedwindow) takes 
one or more widgets and displays them in a horizontal row or vertical 
column. The widgets are separated by a sash that the user can manipulate 
with the mouse. When the sash is moved, each widget on either side of the 
sash is resized. Figure 21.15 illustrates a panedwindow with two panes. 
The left pane contains a frame with a listbox and a scrollbar. The right pane 
contains a frame with a text widget and scrollbars. The sash width and the 
handle size are fully configurable. 


Figure 21.15 The panedwindow widget has features of a geometry manager. 
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Sash Drag cusor 


kparewendow tcl 


ChApter Gecaetry Mgtager Panedwindow Example 


~listvariable filelict \ 

yecrollcommand “.left.veb set 

ttk::ecrollbar .left.veb -command “.left.lincbox yview 
grid .left.listbox -row © -column © -sticky naew 

grid .left.veb -rew 0 ~colusn 1 -#tacky na 

grid columnconfigure .left o -weight 1 

grid rowoonfigure .left 6 -weight i 


oll right.hsb set 
ttk:i:@erollbar .right.veb ~ccmman 


right.t yriew orient vertical 
tck: :e#crollbar fight.heb -ccamas -Fight.t xview" -orient horizontal 
grid .right.t -row 0 -colunn © tacky naew 
grid .right.veb -rce o eticky ns ~ 


Left pane Right pane 


Similarly, the themed notebook widget, ttk::notebook, serves in part as a 
geometry manager. When you add more widgets for it to manage, it displays 
a set of tabs corresponding to those slaves. All the slaves are unmapped 
except for the one whose tab is selected. Selecting a different tab unmaps 
the current slave and maps the slave of the tab selection. Figure 21.16 
shows an example of a notebook with three tabs. The selected tab has 
mapped a slave frame containing a gridded text widget and vertical and 
horizontal scrollbars. 


Figure 21.16 The notebook widget has features of a geometry manager. 
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Simple ttk Text Editor 


|] cursors. tel! | ‘] ttk_buttons. tcl [J notebook. tel 


# 
# Notebook example 


# Tcl and the Tk Toolkit, 2nd Edition 
# 


ttk::frame .f 
set nb [ttk::notebook .f.nb] 


pack $nb -fill both -expand 1 
pack .f -fill both -expand 1 


# Define menu bar 

menu .mbar 

menu .mbar.file 

-tbar.file add command -label "'Open..."' -command "addFile $nb" 

-tnbar.file add command -label "Save" -command "saveFile $nb" 

Minbar. file add command -label "Save As..."" command "'saveAs $nb" 

-mbar.file add separator 

-Mnbar.file add command -label "Close Window" -command "closeWindow $nb" yy 


Finally, the wn command is used to manage toplevel windows, typically 
windows created using the topiever command, but it can also be used to 
“dock” (stop managing a toplevel window) or “undock” (make into a 


toplevel window) any widget. See Chapter 26 for more details on the um 
command. 
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22. Events and Bindings 


You have already seen that Tcl scripts can be associated with widgets such 
as buttons or menus so that the scripts are invoked when certain events 
occur, such as clicking a mouse button over the widget. These mechanisms 
are provided as specific features of specific widget classes. Tk also 
provides a more general mechanism called bindings, which allow you to 
create handlers for any event in any window. A binding “binds” a Tcl script 
to an event or sequence of events in one or more windows so that the script 
is evaluated whenever the given event sequence occurs in any of the 
windows. You can use bindings to extend the basic functions of a widget, 
for example, by defining shortcut keys for common actions. You can also 
override or modify the default behaviors of widgets, since they are 
implemented with bindings. 


22.1 Commands Presented in This Chapter 


This chapter discusses the following commands for manipulating events and 
bindings: 

* bind tag sequence script 
Arranges for script to be evaluated each time the event sequence given by 
sequence occurs in the window(s) given by tag. If a binding already exists for 
tag aNd sequence, It is replaced. If script 18 an empty string, the binding for tag 
and sequence 18 removed, if there is one. If the first character of script 1s +, the 
script is appended to any existing script for the binding. 

* bind tag sequence 
If there is a binding for tag and sequence, returns its script. Otherwise it 
returns an empty string. 

® bind tag 
Returns a list of the sequences for which tag has bindings. 

* bindtags widget ?tagList? 
Sets the bindings tags associated with widget to tagrist. Returns a list of 
binding tags currently associated with wiaget if cagrist 18 omitted. 


® event add <<virtual>> sequence ?sequence...? 


Associates the virtual event virtua: with the physical event sequence(S). 


event delete <<virtual>> ? sequence sequence...? 
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Deletes each sequence from those associated with the virtual event given by 
virtual. IfNO sequence 18 given, all sequences are removed. 


vent generate widget event ?option value option value ...? 
Generates a window event and arranges for it to be processed just as if it 
had come from the window system. wiaget gives the path name of the 
window for which the event is generated. event may have any of the forms 
allowed for the sequence argument of the »ina command except that it must 
consist of a single event pattern, not a sequence. The option value pairs given 
are used in the « substitutions for the event binding. 

® event info ?<<virtual>>? 
Returns sequences associated with a specified virtual event or a list of 
currently defined virtual events if no event is specified. 


22.2 Events 


An event is a record generated by the windowing system to notify an 
application of a potentially interesting occurrence. Each event has a type 
that indicates the general sort of thing that occurred. The event types that are 
most commonly used in bindings are those for user actions such as key 
presses or changes in the pointer position. There are many other event types, 
such as those generated when windows change size, when windows are 
destroyed, when windows need to be redisplayed, and so on. The following 
are the most commonly used event types, but see the reference 
documentation for the bina command for details: 
* Key OF KeyPpress—A key was pressed. 
* KeyRelease—A key was released. 
* Button OF ButtonPress—-A mouse button was pressed. 
* ButtonRelease—A mouse button was released. 
* enter—The mouse pointer moved into a widget (it is now over a 
visible portion of the widget). 
* teave—The mouse pointer moved out of a widget. 
* motion—The mouse pointer moved from one point to another within a 
single widget. 
* Mousewhee1—T he user moved the mouse wheel. 
* rocusin—A widget received keyboard focus. 
* rocusout—A widget lost keyboard focus. 
* configure—A widget was initially displayed or changed its size, 
position, or border width. 
* map—A widget became viewable. 
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* unmap—A widget is no longer viewable. 
* pestroy—A widget has been destroyed. 


Note 


Commands that reference event types and their modifiers are case- 
sensitive. Make sure that you have the exact capitalization for the event 
type and its modifiers, or the command will raise an error. 


In addition to its type, each event also contains several other fields. For 
mouse events, one of them specifies a widget and two others give the x- and 
y-coordinates of the pointer within the widget. For <enter> and <neave> events, 
the widget is the one just entered or left. For <suttonPress>, <ButtonRelease>, and 
<Motion> events, the widget is the one currently under the pointer. For 
<keyPress> @Nd <keyrelease> events, the widget is the one that has the 
application’s input focus (see Chapter 27 for details on the input focus). 
Button and key events also contain a field called the detail, which indicates 
the particular button or key that was pressed. For <suttonpress> and 
<ButtonRelease> events, the detail is a button number, where : usually refers to 
the leftmost button on the mouse. For <xeypress> and <xeyrelease> events the 
detail is a keysym (key symbol), which is a textual name describing a 
particular key on the keyboard. The keysym for an alphanumeric ASCII 
character such as a or a or 2 1s just the character itself. Some other examples 
of keysyms are return for the carriage-return key (often labeled “Enter” on 
modern keyboards), sackspace for the Backspace key, peicte for the Delete 
key, and seip for the Help key. The keysym for a function key such as F1 is 
normally the same as the name that appears on the key. Section 22.6 contains 
a script that you can use to find out the keysyms for the keys on your 
keyboard. 

Certain keys are defined as special modifier keys; these include the Shift 
keys, the Control key, the Command and Option keys on standard Mac 
keyboards, plus other keys such as Meta and Alt. The events just listed 
contain a state field that identifies which of the modifier keys were pressed 
at the time of the event and which mouse buttons were pressed. The state 
field is useful, for example, to trigger a script when the pointer moves with 
button 1 down, or when ceri+a 1s typed on the keyboard. 

Events also contain other fields besides the ones described; the exact set of 
fields varies from event to event. See the reference documentation for a 
complete list of fields available for each event type. 
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22.3 An Overview of the 1i.n Command 


The pina command is used to create, modify, query, and remove bindings. 
This section illustrates the basic features of bina, and later sections go over 
the features in more detail. 

Bindings are created with commands like this one: 


bind .entry <Control-KeyPress-d> {.entry delete insert} 


The first argument to the command specifies the path name of the window to 
which the binding applies. It can also be a widget class name such as entry, 
in which case the binding applies to all widgets of that class (such bindings 
are called class bindings), or it can be a11, in which case the binding 
applies to all widgets. You can also create your own symbolic binding tag, 
as described in Section 22.8. The second argument specifies a sequence of 
one or more events. The example specifies a single event, which is a 
keypress of the a character while the contro1 modifier key is down. The third 
argument may be any Tcl script. The script in the example invokes .entry’s 
widget command to delete the character just after the insertion cursor. The 
script is invoked 1f controi+a 18 typed when the application’s input focus is in 
.entry. The binding can trigger any number of times. It remains in effect until 
.entry 18 deleted or the binding is explicitly removed by invoking pina with 


an empty script: 


bind .entry <Control-KeyPress-d> {} 


A background error occurs if there is an error during the execution of the 
script. The default behavior when a background error occurs in a Tk script 
is to post a dialog informing the user of the error. You can change this 
behavior, as described in Section 13.6. 

The vina command can also be used to retrieve information about bindings. 
If bina 1s invoked with an event sequence but no script, it returns the script 
for the given event sequence: 


bind .entry <Control-KeyPress-d> 
= .entry delete insert 


If bina is invoked with a single argument, it returns a list of all the bound 
event sequences for that window or class: 
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bind .entry 
= <Control-Key-d> 
bind Button 


=> <ButtonRelease-1> <Button-1> <Leave> <Enter> <Key-space> 


The first example returned the bound sequences for .entry, and the second 
example returned information about all of the class bindings for button 
widgets. The class bindings were created by Tk’s initialization script (the 
file button.tc1 in the Tk library directory) to establish the default behavior 
for button widgets. 


22.4 Event Patterns 


Event sequences are constructed from basic units called event patterns, 
which Tk matches against the stream of events received by the application. 
An event sequence can contain any number of patterns, but most sequences 
have only a single pattern. 

The most general form for a pattern consists of one or more fields between 
angle brackets, with the following syntax: 


<modifier- modifier...- modifier- type-detail> 


Whitespace may be used instead of dashes to separate the various fields, 
and most of the fields are optional. The type field identifies the particular 
event type, such as xeypress OF Enter. See Section 22.2 for a list of common 
event types. For example, the following script causes an entry widget .entry 
to change to a light green background whenever the mouse passes over it 
and to return to a white background when the button passes out of the widget 
again: 


bind .entry <Enter> {.entry config -background lightgreen} 
bind .entry <Leave> {.entry config -background white} 


For key and button events the event type may be followed by a detail field 
that specifies a particular button or keysym. If no detail field is provided, as 
IN <xeypress>, the pattern matches any event of the given type. Ifa detail field 
is provided, as in <keyrress-Escape> OF <ButtonPress-2>, the pattern matches only 
events for the specific key or button. If a detail 1s specified, you can omit the 
Key OF Button event types: <Escape> 18 equivalent to <xeypress-Escape>. 


Note 
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The pattern <i> 1s equivalent to <sutton-1>, NOt <KeyPress-1>. 


The event type may be preceded by any number of modifiers, each of which 
must be one of the values given in Table 22.1. If modifiers are specified, the 
pattern matches only events that occur when the specified modifiers are 
present. For example, the pattern <snirt-controi-a> requires that both the Shift 
and Control keys be held down when a is typed, and <s1-motion> requires that 
the pointer move when mouse button 1 1s down. 


Table 22.1 Modifier Names for Event Patterns; Comma-Separated 
Modifiers Are Equivalent 


Control] Modi, Ml, Command Buttonl, Bl 
Shift Mod2, M2, Option Button2, B2 
Lock Mod3, M3 Button3, B3 
Alt Mod4, M4 Button3, B4 
Meta, M Mods, M5 Button3, BS 
Double Triple Quadruple 


Not all modifiers are available on all systems. For example, the commana and 
option modifiers are equivalent to moa: and moa2 respectively and correspond 
to Macintosh-specific modifier keys. Some non-Macintosh systems might 
have keyboards with Meta keys that map to these modifiers, but many 
systems may not have keys that generate the moai-moas modifiers. 

The “modifiers” poubie, tripie, and ouadrupie are used for specifying double, 
triple, and quadruple mouse clicks and other repeated events. They match a 
sequence of two, three, or four events, each of which matches the remainder 
of the pattern. For example, <poubie-i> matches a double-click of mouse 
button 1, and <rripie-2> matches any triple-click of button 2. 

A special shortcut form is available for patterns that specify key presses of 
printing ASCII characters such as a or e. You can specify a pattern for these 
events using just the single character. For example, 


bind .entry a {.entry insert insert a} 


arranges for the character a to be inserted into .entry at the point of the 
insertion cursor if it is typed when .entry has the keyboard focus. This 
command 1s identical to the command 


ola 


bind .entry <KeyPress-a> {.entry insert insert a} 


22.5 Sequences of Events 


An event sequence consists of one or more event patterns optionally 
separated by whitespace. For example, the sequence <rscape>a Contains two 
patterns. It triggers when the Escape key is pressed and then the a key is 
pressed. 

A sequence need not necessarily match consecutive events. For example, the 
sequence <zscape>a Matches an event sequence consisting of a Keypress ON 
Escape, @ KeyRelease Of Escape, and then a press of a; the release Of Escape 18 
ignored in determining the match. Tk generally ignores conflicting events in 
the input event stream unless they have the same type as the desired event. 
Thus, if some other key is pressed between the xscape and the a, the sequence 
does not match. As another example, the sequence as matches a press of the a 
key, a release of the a key, a press of the snirt key, and a press of the » key. In 
this case, the snist key press is ignored because it is a modifier key. Also, if 
several motion events occur in a row, only the last one is used for matching 
binding sequences. 


22.6 Substitutions in Scripts 


The script that handles an event often needs to use some of the fields in the 
event, such as the pointer coordinates or the particular keysym that was 
pressed. Tk provides this access by substituting fields from the event 
wherever there are = characters in the script, in a fashion much like the Tcl 
format Command. Before evaluating the script for a binding, Tk generates a 
new script from the original one by replacing each « and the character 
following it with information about the event. The character following the « 
selects a specific substitution to make. There are about 30 substitutions 
defined, but Table 22.2 lists the most commonly used ones. Not all 
substitutions are available for each event type. See the reference 
documentation for complete details of the substitutions available for 
different event types and their meanings. 


Table 22.2 Common Event Detail Substitutions 


514 


Sequence Substitution 


%% Replaced with a single percent 

$b The number of the button that was pressed or released. Valid only for 
ButtonPress and ButtonRelease events. 

+d The event detail in an event-specific format for built-in events. For virtual 


events generated with the event generate command, this can be an 
arbitrary string value provided to the event generate command. See 
the reference documentation for more details. 


th The window height value for the event 

$t The time value for the event 

tw The window width value for the event 

%x The x-coordinate of the mouse pointer 

ty The y-coordinate of the mouse pointer 

$A The Unicode character value corresponding to a KeyPress or KeyRelease 


event, or an empty string if the event is for a key such as Shift that 
doesn’t have a Unicode equivalent. 


$D The delta value of a MouseWheel event, representing the rotation units 
the mouse wheel has been moved. The sign of the value represents the 
direction the mouse wheel was scrolled. 


$K The keysym from KeyPress or KeyRelease event 

=W The full widget path name of the widget receiving the event 

+X The x-coordinate of the mouse pointer relative to the root window 
%Y The y-coordinate of the mouse pointer relative to the root window 


As an example of using substitutions, the following script implements a 
simple mouse tracker: 


bind all <Enter> {puts "Entering *W at (%x,%y)"} 
bind all <Leave> {puts "Leaving %w"} 
bind all <Motion> {puts "Pointer at (%x,%y)"} 


If you type these commands in wish, messages are printed as you move the 
pointer over the windows of the application. Or you can use the following 
script to determine the keysyms for the keys on your keyboard: 


bind . <KeyPress> {puts "The keysym is %K"} 
focus . 


If you type these two commands in wisn, the name of the keysym will be 
printed for any key that you type. Try typing some normal keys like a, a, and 
1, plus special keys like F1, Return, or Shift. 
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Note 


When Tk makes = substitutions, it treats the script as an ordinary string 
without any special properties. The normal quoting rules for Tcl 
commands are not considered, so = sequences are substituted even if 
embedded in braces or preceded by backslashes. The only way to 
prevent a « substitution is to double the « character. 


22.7 Conflict Resolution 


It 1s possible for several bindings to match a single event. For example, 
suppose there are bindings for <sutton-1> and <poubie-Button-1>, and button | is 
clicked three times. The first button press event matches only the <sutton-1> 
binding, but the second and third presses match both bindings. The way 
conflicts are handled depends on how the bindings were declared. If the 
same tag is used for all the matching bindings, as in 


bind .b <Button-1>... 
bind .b <Double-Button-1> ... 


exactly one binding triggers, and it is the most specific of all the matching 
bindings. <poubie-Button-1> 18 more specific than <sutton-i>, so its script is 
executed on the second and third presses. Similarly, <zscape>a 18 more 
specific than <xey-a>, <control-Key-a> 18 More specific than <xey-a>, and <xey-a> 
is more specific than <xeypress>. 
If more than one binding matches a particular event and the bindings have 
the same tag, the most specific binding is chosen and its script is evaluated. 
The following tests are applied, in order, to determine which of several 
matching sequences is more specific: 
1. An event pattern that specifies a specific button or key is more 
specific than one that doesn’t. 
2. A longer sequence (in terms of number of events matched) 1s more 
specific than a shorter sequence. 
3. If the modifiers specified in one pattern are a subset of the modifiers 
in another pattern, the pattern with more modifiers is more specific. 
4. If these tests fail to determine a winner, the most recently registered 
sequence is the winner. 
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As an example, consider a label widget given only a single binding for the 
event <sutton-1>! 


label .1 -text "Sample 1" 
bind .1 <Button-1> { 
puts "Left mouse button pressed" 

} 
This event matches a <sutton-1> event and a <snift-Button-i> event. In the 
following case, the label is given two bindings, one with the snist modifier 
and one without: 

label .1 -text "Sample 2" 


f 


bind .1 <Button-1> { 
puts "Left mouse button pressed" 

\ 

J 


bind .1 <Shift-Button-1> { 


puts "Shift-Left mouse button pressed" 

} 
Because this widget has two bindings, event matching distinguishes the two 
different cases, and the presence of the more specific binding prevents the 


binding without the modifier from triggering if it matches. 


22.8 Event-Binding Hierarchy 


So far we’ve focused on bindings for a specific window, but actually there 
is a hierarchy of bindings that process events. Each window has a list of 
bindtags, also known simply as tags. Each bindtag in the list can contain a 
set of event bindings. Suppose that there are matching bindings with 
different tags, as in the following example: 


bind all <Return> ... 
bind .b <Any-KeyPress> ... 


If the Return key is pressed, both of these bindings match. The different tags 
are handled independently, so that the matching binding triggers for each 
kind of tag. The order in which these tags are evaluated 1s defined with the 
bindtags Command: 


bindtags widget ?tagList? 


The tagzist 18 a list of tags in the order in which they are searched for event 
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matching. By default, a widget is given four tags in the following order: the 
widget itself, the widget’s class name, the toplevel window containing the 
widget, and a1. If the binatags command 1s issued with a single argument, it 
returns the current tag list for the specified widget. So for the widget .» in 
the preceding example, the default tag list is 


bindtags .b 
= .b Button. all 


This means that the binding for .» triggers first, followed by the binding for 
all When the Return key is pressed. 

The tag list can be modified to change the tag order, or to add or remove 
windows, classes, or even user-defined tags. For example, since the 
behavior of a button is defined with bindings on the sutton class, new 
behavior of a button can be assigned to a new tag, say, speciaiputton; simply 
changing the bindtags for a given button instantly changes the button’s 
behavior, like so: 


bind SpecialButton <Return> { # Some script... } 


bindtags .b {.b SpecialButton . all} 


Sometimes it’s necessary to prevent event bindings farther up the hierarchy 
from triggering. This can be done by using the »reax command or the return - 
code break Command. Whenever the binding code for an event returns a 
“break” status, further processing of the bindtags list is halted. For example, 
changing the previous example like this: 


bind all <Return> {puts "all return!"} 
bind .b <Return> {puts ".b return!"; break} 


changes the behavior so that the 211 binding is not triggered, at least not for 
the .» window. The break command can be used within the body of the bind 
script. If the bind script calls a Tcl procedure, the procedure must use the 
return -code break Command to return a break condition from the procedure 
itself to have the same effect. 


22.9 When Are Events Processed? 


Tk processes events only at a few well-defined times. After a Tk 
application completes its initialization, it enters an event loop to wait for 
window system events and other events such as timer and file events. When 
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an event occurs, the event loop executes C or Tcl code to respond to that 
event. Once the response has completed, control returns to the event loop to 
wait for the next interesting event. Almost all events are processed from the 
top-level event loop. New events are not considered while the event loop 
responds to the current event, so there normally is no danger of one binding 
triggering in the middle of the script for another binding. This approach 
applies to all event handlers, including those for bindings, those for the 
script options associated with widgets, and others yet to be discussed, such 
as window manager protocol handlers. 


Note 


A few special commands, txwait, vwait, and update, explicitly invoke the 
event loop. If called from within an executing event handler, they 
invoke nested instances of the event loop, which often causes 
unexpected effects. The best practice is not to call these commands 
from within your event-handling scripts. Commands and procedures 
that invoke the event loop should be specially noted in their reference 
documentation, so watch out for this. All other commands complete 
immediately without reentering the event loop. 


Event handlers are always invoked in the global scope of the global 
namespace, even if the event loop was invoked from a txwait, vwait, OF update 
command inside a procedure. This means that you should use only global 
variables or fully qualified namespace variables in binding scripts. The 
context in which a handler is evaluated is not the same as the context in 
which the handler was defined. For example, suppose that you invoke pina 
from within a procedure. When the script in the binding eventually triggers, 
it does not have access to the local variables of the procedure; in most cases 
the procedure will have returned before the binding is invoked, so the local 
variables don’t even exist anymore. 

The best practice is to use Tcl procedures to implement a binding script, 
especially if the script needs to use temporary variables in order to process 
the event. This keeps the global namespace from becoming too cluttered 
with temporary variables. It can also prevent latent bugs when temporary 
variables are inadvertently shared. Another good practice for sharing 
variables is to use namespaces. (Namespaces are discussed in depth in 
Chapter 10.) Namespace variables can be shared by namespace-defined 
procedures, thereby isolating potential inadvertent interaction problems. 
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There is no problem having a bind script call a namespace-defined 
procedure; simply use a fully qualified name when calling the procedure, as 
shown here: 


namespace eval SpecialButton { 

variable last_x 

variable last y 

proc bl event {wx y} { 
variable last_x 
variable last_y 
set last_x $x 
set last_y $y 
puts "Button-1 pressed" 
puts "at location $x,$y" 
puts "in window SW" 


} 


bind .b <Button-1> {SpecialButton::bl_event %W %x %y} 
The other advantage to using Tcl procedures is performance. The Tcl 
interpreter bytecode compiles procedure bodies for performance. Because 
of the substitutions that take place each time a binding 1s triggered, a binding 
script cannot be bytecode-compiled. When a Tcl procedure is invoked from 
a binding, the procedure body can be compiled, improving the performance 
of the event handling. 


22.10 Named Virtual Events 


Tk’s bindings provide an effective way to link actions from the windowing 
system or from user input to tasks within the application. This is possible 
with named virtual events. Let’s look at how these may be put to use. 
Here’s an example of a typical application binding: 


bind .text <Control-c> {tk_textCopy %W} 


Now this binding may be repeated for other widgets in the application as 
well. Windows applications commonly use <controi-c> for a copy shortcut; 
however, on the Apple Macintosh, this operation is commonly performed 
USING <command-c>. It would be cumbersome and error-prone to have to modify 
every event binding in order to simply change the shortcut key for a given 
operation. By using virtual events, we can simplify keyboard shortcut 
assignments. First, create the binding to a named virtual event: 
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bind .text <<Copy>> {tk_textCopy %W} 


You would do this for every widget or widget class that supports the copy 
action. Next, tie the physical key binding to the named virtual event using the 
Tk event command: 


event add <<Copy>> <Control-c> 


This needs to be done only once. Defining a new shortcut is as easy as 
adding a new event definition: 


event add <<Copy>> <Command-c> 


So now there are two shortcuts for the copy operation, <controi-c> and 
<command-c>. The former shortcut can be removed with the event delete 
command: 


event delete <<Copy>> <Control-c> 


Of course, there are situations where having both platforms’ event 
sequences associated with the virtual event could cause incompatibilities. In 
cases like these, you can use the tx windowingsystem Command, described in 
Chapter 29, to determine on which windowing system your application is 
running, and then set up only the virtual event definitions appropriate for that 
platform. For example, consider the case of binding scripts to a “right 
mouse click.” Most Windows and Unix systems use three-button mice, and 
the right-click is delivered as a <suttonpress-3> event. However, it is common 
for mice on Macintosh systems to have only a single button, and holding 
down the Control key while clicking is often used as the equivalent of a 
right-click. And even on those Macintosh systems that have a multibutton 
mouse, the right-click is delivered as a <suttonpress-2> event. So you could 
define a virtual event named <<rightclick>> aS follows: 


if {{tk windowingsystem] eq "aqua"} { 
# Set up Mac OS X virtual event definitions 
event add <<RightClick>> <Button-2> <Control-Button-1> 
} else { 
# Set up Windows and Unix virtual event definitions 
event add <<RightClick>> <Button-3> 


} 


If a virtual binding has the same sequence as a physical binding, the 
physical binding always takes precedence. So if both 
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bind .text <Control-C> {puts "copy % W"} 


and 


bind .text <<Copy>> {tk_textCopy %W} 
event add <<Copy>> <Control-c> 


exist, the puts command executes, as this physical binding takes precedence 
over the <<copy>> virtual binding. 

Tk predefines some common operations as virtual events for widget 
bindings. The defaults for these are already platform-appropriate, so it is 
unlikely that your application needs to change them. Table 22.3 lists the 
predefined virtual events in Tk for user actions. 


Table 22.3 Predefined Tk Virtual Events for User Actions 


Virtual event Description 

<<Clear>> Deletes the currently selected widget contents 

<<Copy>> Copies the currently selected widget contents to the 
clipboard 

<<Cut>> Moves the currently selected widget contents to the 
clipboard 

<<Paste>> Replaces the currently selected widget contents with the 
contents of the clipboard 

<<PasteSelection>> Inserts the contents of the selection at the mouse location 
(this event has meaningful $x and %y substitutions) 

<<PrevWindow>> Traverses to the previous window 

<<Redo>> Redoes one undone action 

<<Undo>> Undoes the last action 


22.11 Generating Events 


In addition to managing named virtual events as described earlier, the event 
command has the generate option, which can generate any windowing system 
event and send it to any window in the application, as if it came from the 
windowing system. Being able to generate events provides a means of 
testing an application’s user interface. The syntax of event generate 1S 


event generate widget event ?option value option value ...? 
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Button presses, mouse motions, and key presses can all be emulated with the 

vent generate COMmand. The option vaiue pairs define the attributes of the 
event, such as the mouse position. (See the reference documentation for a 
complete list of supported options.) For example, the following command 
generates a mouse button event: 


event generate .copy <ButtonPress> -button | -x 10 -y 10 


In this case, the press is for button 1, normally the leftmost mouse button. In 
addition, the command provides the mouse location relative to the upper-left 
corner of the widget, which Tk uses for event-handling scripts with sx and 
zy. In this example, the event is delivered to the widget .copy, but the mouse 
pointer remains in its position on the screen. The event generate Command 
also supports a -warp option, which, if provided a Boolean true value, also 
moves the mouse pointer. 

You can also generate virtual events. The virtual events you generate don’t 
even have to have a physical event sequence associated with them. This can 
serve as the basis of an asynchronous message-passing system in your 
application. For example, consider the following code: 


label .display -textvariable msg -width 30 -anchor w 
grid .display -sticky ew 
bind .display <<Message>> { 


\ 


set msg "[clock format %t -format %$$T]: %d" 
i 
J 
event generate .text <<Message>> \ 

-data "Hello" -time [clock seconds] 


In this example, the widget named .aispiay recelves a <<Message>> event. The - 
data Option allows you to pass an arbitrary string value with the event, which 
the event binding can retrieve via the sa event substitution; the -time option 
allows you to set a timestamp that can be retrieved with the st substitution. 
In this example, the event handler simply formats the information received 
and sets the value of the label’s linked text variable. 

Another use of the event generate command is to tie a command action to a 
widget’s virtual binding; for example: 
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button .copy -text Copy -command { 
event generate [focus] <<Copy>> 


or 


.menu.edit add command -text Copy \ 
-command {event generate [focus] <<Copy>>} 


or 


-menu.edit add command -text Copy \ 
-command {event generate [focus] <<Copy>>} 


In this way, a single button or menu command can be tied to whichever 
widget has the keyboard focus at the time the button is pressed. 


22.12 Logical Actions 


Most of the bindings discussed so far deal with interactions between the 
application and the user or between the application and the windowing 
system. Named virtual events and bindings can also be employed as a means 
of messaging or signaling between various widgets and the application. This 
is best illustrated through an example. We’ll use a simple text editor to 
demonstrate how virtual events can be employed between the text widget 
and an application toolbar. 

The text editor example contains a toolbar with buttons for copy, cut, and 
paste operations. When a selection is made in a text widget, the cut and 
copy buttons in the application’s toolbar, as well as the Cut and Copy menu 
items in the Edit menu, should change to an enabled state. The text widget 
automatically generates a <<selection>> event whenever its selection changes. 
This allows each of the widgets that care about selection to create a binding 
ON <<selection>> and update their states accordingly: 


bind all <<Selection>> {updateToolbar %W} 


In this example, the code binds to all widgets, so that no matter where the 
selection may occur, the toolbar gets properly updated. In the code that 
follows, the toolbar buttons are enabled and disabled based on whether text 
is selected. 

The updateroolbar procedure examines the selection state of the widget «w to 
see if the selection is empty or not. It uses two other virtual events, 
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<<MayCopy>> and <<maycut>>, to propagate the selection state to all the widgets 
that need to know: 


proc updateToolbar {w} { 
set class [winfo class §$w] 
if {Sclass eq "Text"} { 
set select _ range [$w tag ranges sel] 
if {[llength $select range] > 0} { 

set state normal 
} else { 

set state disabled 
i 
J 
event generate Sw <<MayCopy>> -data $state 
event generate $w <<MayCut>> -data $state 


} 


At this point, you could simply hard-code the binding scripts for the 
<<MayCopy>> and <<maycut>> events to update the appropriate menu entries and 
toolbar buttons. However, you might envision a modular application that 
could be extended with optional add-ons. These add-ons might need 
notification about when copies and cuts may take place. In this case, taking 
advantage of the bina command’s ability to extend an existing binding script 
is quite useful. Remember that if the script argument to bina has + as its first 
character, the script is appended to any existing binding script rather than 
overwriting it. Thus, we could have our components register their interest in 
the copy/cut notification like this: 


bind all <<MayCopy>> \ 

"+. toolbar.copy configure -state %d" 
bind all <<MayCut>> \ 

"+. toolbar.cut configure -state %d" 
bind all <<MayCopy>> \ 

"+.mbar.edit entryconfigure 0 -state %#d" 
bind all <<MayCut>> \ 

"+.mbar.edit entryconfigure 1 -state %d" 


Now when the <<maycopy>> OF <<maycut>> event 1s generated, the code updates 
toolbar buttons to copy and cut text, respectively. The code also updates the 
menu items to copy and cut text. 

Likewise, binding the text widget to a <<cut>> event and having the toolbar 
button and menu entry command generate a <<cut>> event associate the action 
with the widget without one window having to have direct knowledge of the 
other. Note that the text widget already contains a binding for the <<copy>> and 
<<cut>> virtual events, so all that is needed is to generate this event when the 
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toolbar button is pressed: 


button .toolbar.copy \ 

-image copy-image \ 

-command {event generate [focus] <<Copy>>} 
button .toolbar.cut \ 

-image cut-image \ 

-command {event generate [focus] <<Cut>>} 


-mbar.edit add command -label Copy 

-command {event generate [focus] <<Copy>>} 
-mbar.,edit add command -label Cut \ 

-command {event generate [focus] <<Cut>>} 


With this technique, the code merely issues an event indicating a cut or copy 
operation, letting the Tk text widget handle the rest. The socus command tells 
the code which widget has the text focus. That widget is the one used for 
copying or cutting text. Like this example, Tk’s virtual events provide a 
surprising amount of power, especially when you make use of the 
preexisting body of Tcl code designed to handle these events. 

Figure 22.1 shows an example of the editor in its initial state, with no text 
selected. Note how the toolbar buttons are disabled. As soon as something 
is selected, the copy and cut toolbar buttons become enabled, as shown in 


Fipure 222. 


Figure 22.1 The toolbar buttons before selecting text. The icons in this 
figure are from the Tango Desktop Project 


(http://tango. freedesktop.org/Tango_ Desktop Project). 


# Example using virtual events to update a toolbar state 
# 


# Load images for toolbar icons 

image create photo copy-image -file edit-copy.gif 
image create photo cut-image -file edit-cut.gif 
image create photo paste-image -file edit-paste.gif 


Figure 22.2 The toolbar buttons after text is selected. The icons in this 
figure are from the Tango Desktop Project 
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(http://tango. freedesktop.org/Tango_Desktop_Project). 


# Example using to update a toolbar state 
# 


# Load images for toolbar icons 

image create photo copy-image -file edit-copy.gif 
image create photo cut-image -file edit-cut.gif 
image create photo paste-image -file edit-paste.qgif 


After some text is selected, the cut button is pressed. At this point the copy 
and cut buttons become disabled because there is nothing selected, and the 
paste button becomes enabled because there is now text in the clipboard. 
Figure 22.3 reflects this state. 


Figure 22.3 The toolbar buttons after the selected text is cut. The icons in 
this figure are from the Tango Desktop Project 
(http://tango. freedesktop.org/Tango_Desktop_Project). 


# Example using to update a toolbar state 
# 


# Load images for toolbar icons 

image create photo copy-image -file edit-copy.gif 
image create photo cut-image -file edit-cut.gif 
image create photo paste-image -file edit-paste.qif 


As applications grow more complex, the number of widget interactions can 
make user interface development a daunting task. When widget commands 


and states are organized into logical actions, the interactions become 
manageable. 


22.13 Other Uses of Bindings 
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The binding mechanism described in this chapter applies to widgets. 
However, similar mechanisms are available internally within some widgets. 
For example, canvas widgets allow bindings to be associated with 
graphical items such as rectangles or polygons, and text widgets allow 
bindings to be associated with ranges of characters. These bindings are 
created using the same syntax for event sequences and = substitutions, but 
they are created with the widget command for the widget and refer to the 
widget’s internal objects instead of to windows. See Chapter 23 for more 
information on the canvas widget and Chapter 24 for more information on 
the text widget. 
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23. The Canvas Widget 


This chapter describes Tk’s canvas widget. Canvases allow you to display 
and manipulate a variety of graphical objects such as rectangles, lines, 
images, and text strings. The canvas widget supports powerful features of 
allowing you to tag objects and manipulate all the objects with a given tag. 
For example, you can move or recolor all of the items with a given tag. You 
can also create event bindings for tags so that a Tcl script 1s invoked 
whenever the pointer passes over a tagged rectangle in a canvas, whenever 
a button is pressed over a string in the widget, and so on. The tagging and 
binding mechanisms make it easy to “activate” text and graphics so that they 
respond to the mouse. This chapter provides an introduction to canvases and 
shows some examples. It doesn’t cover every detail, however; for that you 
should consult the reference documentation. 


23.1 Canvas Basics: Items and Types 


A canvas is a widget that displays a two-dimensional drawing surface on 
which you can place items of various types. Tk currently supports the 
following types: 

* rectangle—drawn as an outline or a filled area; you can specify the 
outline color, outline width, fill color, and fill stipple pattern. 

* ovai—for circles and ellipses, with the same attributes as rectangles. 

* 1ine—consisting of one or more connected segments, a width, a color, 
a stipple pattern, and several other attributes such as whether to 
miter or round the corners between segments and whether or not to 
draw arrowheads at the ends of the line. 

¢ Bézier curves—iine items with an additional -smootn attribute 
specifying how Bézier cubic splines should be drawn instead of 
straight segments. 

* polygon—consisting of three or more points, a fill color, and a stipple 
pattern. As with 1ine items, you can also use the -smootn attribute to 
specify that the outline of the polygon should be a Bézier curve 
instead of a collection of straight segments. 

* arc—drawn in any of several styles such as a pie wedge or a section 
of a circle. You can specify attributes such as the arc’s angular 
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range, outline width, outline color, fill color, and fill stipple. 

* text—consisting of one or more lines drawn in a single font. You can 
select a font, color, stipple pattern, justification mode, and line 
length. 

* pbitmap—consisting of a bitmap name, background color, and 
foreground color. 

* image—consisting of a photo or bitmap image created using the Tk 
image create Command or any of the Tk image extensions. 

* window—an embedded widget of any kind, in which case the canvas 
acts aS a geometry manager for the widget. The canvas reference 
documentation and command syntax use the term window to refer to 
these embedded widgets. 

To create a canvas widget, use the canvas command: 


canvas widgetName ?option value ...? 


The canvas widget supports most standard widget options, such as - 
background to set the background color and -vorderwiath to set the width of the 
widget’s border. You can also request the -neignt and -wiatn for the canvas 
using any supported Tk screen distance, as described in Section 18.2.2, 
though the geometry manager used to display the canvas may override the 
requested size (as discussed in Chapter 21). 

The create subcommand creates new items on the canvas. For example, here 
is a script that creates a canvas named .c and then creates a new rectangle 
item on it: 


canvas .c 

grid .c -sticky nsew 

.c create rectangle 1c 2.5c 4c 4.75c -width 2m \ 
-outline blue -fill yellow 


The first argument after the create action gives the type of the item. 
Following the type are pairs of x- and y-coordinates. The coordinates are 
floating-point values specifying any screen distance supported by Tk, as 
described in Section 18.2.2. When the canvas widget is created, its upper 
left corner is the o, o origin, and the coordinates increase going down and to 
the right. The x- and y-coordinates may be provided either as separate 
arguments or as a single list argument following the type. 

For rectangles there must be exactly four coordinates giving the locations of 
opposing corners of the rectangle. Ovals and arcs require four coordinates 
describing opposing corners of a rectangle bounding the entire oval. Lines 
accept coordinates for two or more points describing connected line 
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segments. Polygons accept coordinates for three or more points describing 
the vertices; Tk automatically connects the last to the first point specified. 
All other types require coordinates of a single positioning point for the 
item. The -anchor option for those types then determines the location of the 
item positioned on the positioning point. For example, -anchor nw positions 
the upper left corner of the item on the positioning point. 

Following the coordinates can be pairs of arguments specifying 
configuration options. The configuration options are specified in the same 
free-form style as for widgets. Default values apply for all options not 
specified. In the preceding example, the outline width, outline color, and fill 
color are specified, but no fill stipple is specified (it defaults to a solid 
fill). See the reference documentation for a complete list of all options 
supported for all types. 

Items on the canvas have a stacking order (sometimes referred to as the 
display list). Items that appear lower in the stacking order (earlier in the 
list) might be obscured by items higher in the stacking order (later in the 
list). Creating a new item places it at the end of the list, on top of all other 
items in the canvas. As mentioned in the next section, you can also raise and 
lower items after creation, changing their stacking order. 


Note 


Window items (embedded widgets) are an exception to the stacking 
order rules. The underlying windowing systems require that they 
always be drawn on top of all other items; they are never obscured by 
other canvas items. If window items embedded within a canvas 
overlap each other, you can use the Tk raise and 1ower commands, 
discussed in Chapter 29, to change their stacking order relative to each 
other. 


Here 1s a script that uses line and text items to create a simple ruler: 


532 


# ruler: draw a ruler on a canvas 
canvas .c -width 12c -height 1.5c 
pack .c 
.c create line 1c 0.5c¢c lc le llc le lic 0.5e 
for {set i 0} {$i < 10} {incr i} { 

set x [expr $i+1] 
create line ${x}c lc ${x}c 0.6c 
create line $x.25c lc $x.25c 0.8c¢ 
create line $§x.5c 1c $x.5c 0.7c 
create line $x.75c 1c $x.75c 0.8c 
.c create text $x.15c .75c -text $i -anchor sw 


Cc 
-C 
-C 

Cc 


} 


Figure 23.1 shows the canvas created by this script. For each centimeter of 
length, four tick marks are drawn with varying heights, along with a text 
item that displays the number of centimeters. No options are specified for 
the line items, since the default values are fine for this example. The option 
-anchor sw for the text items causes their lower left corners to be positioned at 
the specified coordinates. 


Figure 23.1 The canvas generated by the ruier script 
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23.2 Manipulating Items with Identifiers and Tags 


Each item on a particular canvas widget has a unique integer identifier. The 
identifier for an item is returned by the create subcommand, and it can be 
used in other widget commands to refer to the item. For example, you might 
invoke the command 
set circle [.c create oval lc le 2c 2c -fill black \ 
-outline {}] 


fame fal 


to create a solid black circle and save its identifier (12, in this example) in 
the variable circie. Later on you could delete the item with the command 
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.c delete $circle 


The widget command for a canvas provides several subcommands to 
manipulate items: 
¢ YOU CaN move and scaie Items (but not rotate them, as of Tk 8.5). 
¢ You Can raise OF lower them relative to one another (that is, change 
their z-order). 
¢ You can query and change the coordinates (cooras) and configuration 
options (itemcget and itemconfigure) for items. 
¢ You can fina the item nearest a given point, or all the items ina given 
rectangular region, or all the 1tems with a given tag. 
¢ For text items you can insert and delete (achars) text, display and 
manipulate an insertion cursor (icursor), set the focus, and select a 
range of characters. 
¢ You Can pina events to them, such as <suttonpress> OF <KeyPress> events. 
Consult the canvas reference documentation for a complete description of 
all subcommands and their use. 
Canvases also provide a second way of referring to items, called tags. A 
tag is merely a text string associated with an item. A tag may have any form 
except that of an integer. A single item may have any number of tags, and a 
single tag may be applied to any number of items. Once an item has been 
tagged, you can use any of its tags to refer to it: 


.c delete circle 


In this example all of the items with the circie tag are deleted. 

Tags serve three purposes in canvases. First, they allow you to use human- 
readable names for items so that you don’t have to save item identifiers in 
variables. Second, they provide a grouping mechanism so that you can 
manipulate related items together. For example, consider the following 
commands: 


.c itemconfigure circle -fill red 
.c move circle 0 Ic 


The first command changes the fill color to red for all items with the circie 
tag, and the second command moves all the circle items down | centimeter. 
In general you can use a tag name anywhere that you can use an item 
identifier. You can also use simple logical expressions of tags, such as 
circlesselement; See the reference documentation for complete details. 

The third use for tags is for defining behaviors. As discussed in the next 
section, bindings can be associated with tags. This allows groups of items 
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to be responsive to user events. You can also apply multiple tags to an item 
to combine several bound behaviors, or add and remove tags to change an 
item’s behavior dynamically. 

You can assign one or more tags to an item when you create it by providing 
a list of tags as the value of the -tags option, as in the following command: 


.c create oval lc le 2c 2c -fill black -outline {} \ 
-tags {circle element} 


This command assigns both circie and ciement as tags associated with the new 
item. You can also use the itemconfigure Subcommand to assign a different list 
of tags to an existing item by changing the value associated with the -tags 
option. 

The canvas widget command also provides commands for dynamically 
adding or removing tags on items. The atag subcommand removes tags from 
use; for example: 


# Remove the tag "circle" from item 12 

.c dtag 12 circle 

# Remove the tag "highlight" from all items with 
# the tag "element" 


.c dtag element highlight 


# Remove the tag "element" from all items that use it 
.c dtag element 


You can also use the aaatag subcommand to add a tag to one or more items: 


canvas addtag tagName searchSpec 


You need to specify the name of the tag to add as well as a search 
specification for identifying which items should be tagged. Table 23.1 
shows the allowable formats for the search specification. You can also use 
the same format search specifications with the canvas fina subcommand, 
which returns a list of identifiers for all items that match. 


Table 23.1 Canvas Search Specifications 


nh Pe) 


Specification Function 


above tagOrID Selects the item just above the given item 
identified by another tag name or an ID 

all Selects all items on the canvas 

below tagOrID Selects the item just below the given item 


identified by another tag name or an ID 


closest x y ?0ffset? ?start? Selects the item closest to the given position. 
Any item closer than the offset to the posi- 
tion is considered to overlap the position. If 
multiple items are at the same distance or 
overlap at the point, the topmost one is 
selected. The start tag name or ID is used 
to find the closest item after the start item. 


enclosed x1 yl x2 y2 Selects all items enclosed within the given 
rectangle 
overlapping xl yl x2 y2 Selects all items that overlap or are enclosed 


by the given rectangle 
withtag tagOrID Selects all items with the given tag or ID 


The canvas widget automatically manages two additional predefined tags; 
you may not explicitly add or remove these tags. The tag a11 always refers to 
all items on the canvas. The tag current automatically refers to the topmost 
item whose drawn area covers the position of the mouse cursor. If the mouse 
is not in the canvas widget or is not over an item, no item has the current tag. 


23.3 Bindings 


When you create a canvas widget, you can create bindings in the normal 
way using the pina command; these bindings apply to the widget as a whole. 
(See Chapter 22 for a complete discussion of Tk events and using the bina 
command.) In addition, you can create bindings for individual items within a 
canvas using the bina subcommand. This command has the following form: 


.c bind itemOrTag sequence script 


The itemorrag argument gives either the identifier of a single item, in which 
case the binding applies to that one item, or a tag name, in which case it 
applies to all items with the tag. sequence and script specify an event sequence 
and script just as for the bina command. The event sequence may use only 
enter and teave events (which trigger when the pointer moves into or out of an 
item), mouse motion events, button presses and releases, key presses and 
releases, or virtual events. 
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It is possible for multiple bindings to match a particular event, for example, 
if you’ve created bindings for multiple tags and then applied some 
combination of those tags to a particular item. When this occurs, all of the 
matching bindings are invoked, starting with any matching binding on the ai1 
tag, followed by any matching binding for each of the item’s tags (in order), 
followed by any matching binding associated with the item’s ID. If there are 
multiple matching bindings for a single tag, only the most specific binding is 
invoked. A continue command in a binding script terminates that script, and a 
preak Command terminates that script and skips any remaining scripts for the 
event, just as for the pina command. 


Note 


If bindings have been created for a canvas window using the pina 
command, they are invoked in addition to bindings created for the 
canvas’s items using the »ina subcommand. The bindings for items are 
invoked before any of the bindings for the widget as a whole. 


As an example of bindings, the following script allows you to create ball- 
and-stick graphs interactively on a canvas: 
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# graph: simple interactive graph editor 


canvas .c 
pack .c 


# Creates a node (circle) at the given x, y position 
proc mkNode {x y} { 
global nodexX nodeY edgeFirst edgeSecond 
set new [.c create oval [expr {$x-10}] [expr {$y-10}] \ 
{expr {$x+10}] [expr {$y+10}] -outline black \ 
-fill white -tags node] 


# Stores position of the node in two global arrays 
set nodeX($new) $x 
set nodey($new) Sy 


# Creates empty lists for edges in two global arrays 
set edgeFirst ($new) {} 
set edgeSecond($new) {} 


} 


# Draw an edge (line) between two nodes (circles) 
proc mkEdge {first second} { 
global nodeX nodeY edgeFirst edgeSecond 
set edge [.c create line $nodeX($first) $nodeY($first) \ 
$nodex($second) $nodeY ($second) ] 
-c lower Sedge 


# Stores the edge ID in lists held in global arrays 
lappend edgeFirst($first) Sedge 
lappend edgeSecond($second) $edge 


} 


# Draw a node at mouse position every time user clicks 
# left mouse button 
bind .c <ButtonPress-1l> {mkNode tx ty} 
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# Highlight current item by changing its fill color 
.c bind node <Enter> { 

.c itemconfigure current -fill black 
} 


# Remove highlight color 
.c bind node <Leave> { 

.c itemconfigure current -fill white 
} 


# Typing "1" key stores item as first node for a line 
bind .c <KeyPress-1> { 

set firstNode [.c find withtag current] 
} 


# Typing "2" key identifies end of the new line 
bind .c <KeyPress-2> { 
set curNode [.c find withtag current] 
if {($firstNode != "") && ($curNode != "")} { 
mkEdge $firstNode $curNode 
} 


} 


# Assign keyboard focus to the canvas 
focus .c 


If you source this script into wisn, you can create nodes by clicking on the 
canvas with button 1. You can create edges by moving the pointer over a 
node, typing i, then moving the pointer over a different node and typing 2. 
See Figure 23.2 for an example of a graph created with this script. 


Figure 23.2 A graph created interactively using the graph script 
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The script consists of two procedures for creating nodes and edges, plus 
five bindings. The focus command is also required to explicitly assign 
keyboard focus to the canvas widget. The script uses six global variables to 
hold information about the graph: 

* nodex and nodey are associative arrays where the index is the item 
identifier for a node and the value is the x- or y-coordinate of the 
node’s center. This information could be extracted from the canvas 
when needed, but it’s simpler in this case to keep it ina Tcl array. 

* cageFirst ANd eagesecona are associative arrays where the index is the 
identifier for a node and the value is a list of item identifiers for 
edges connecting to the node. ecagerirst holds the identifiers of all 
edges for which a node is the starting point, and cagesecona identifies 
the edges for which a node is the ending point. This information is 
used below to drag nodes interactively. 
firstNode holds the identifier of the node that was under the pointer 
when : was typed last, or an empty string if 1 was typed when the 
pointer wasn’t over a node. 
curnode holds the identifier of the node under the pointer or an empty 
string if the pointer isn’t over a node. 

The mkvode and mkzage procedures just create new items in the canvas and 
record information about them in the global variables. The tower 
subcommand in mxzage causes edges to be placed at the bottom of the display 
list for the canvas so that the nodes appear on top of them. 

The first binding is set for the entire canvas using the pina command; it 
causes a new node to be created at the position of the pointer whenever 
button | is pressed. The enter and teave bindings apply to all the nodes in the 
canvas; they cause nodes to change color when the mouse passes over them. 
The last two bindings are used to create edges; they trigger whenever i or 2 
is typed in the canvas. Both of these bindings make use of the special tag 
current, Which is managed by Tk. The binding for 1 invokes the command 


.c find withtag current 


which returns a list of identifiers for the items that have the tag current (in 
this case the result is either a list with one element or an empty list) and 
saves the result in ¢irstnoae. The binding for 2 retrieves the current item and 
also creates a new edge. 

The following script extends srapn to allow nodes to be dragged 
interactively by holding the Control key while dragging with mouse button 
ie 
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proc moveNode {node xDist yDist} { 
Qlobal nodeX nodeY edgeFirst edgeSecond 
.c move $node $xDist $yDist 
incr nodexX{Snode) $xDist 
incr nodeY(Snode) $yDist 
foreach edge $edgeFirst ($node) { 
.c coords Sedge S$nodeX(Snode) S$nodeY(S$node) \ 
flindex [.c coords Sedge] 2] \ 
{lindex [.c coords Sedge] 3] 
} 
foreach edge S$edgeSecond ($node) { 
.c coords $edge [lindex [.c coords $edge] 0] \ 
[lindex [.c coords Sedge] 1] \ 
SnodexX (Snode}) $SnodeyY ($node) 


} 


.c bind node <Control-ButtonPress-1> { 
set curX %x 
set curY ty 
} 
.c bind node <Control-Bl-Motion> { 
moveNode [{.c find withtag current] [expr {%x-$curx}] \ 
[expr {ty-$curY}] 
set curX %x 
set curYy Sy 


Do nothing on the canvas when receiving these events. This 
binding exists to prevent the "best match" algorithm from 
matching the <ButtonPress-1> canvas binding when all we 
want to trigger is the item binding. 
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bind .c <Control-ButtonPress-1> { } 


The procedure movenode does all the work of moving a node: it uses the move 
action to move the node item, then it updates all of the edges for which this 
node is an endpoint. For each edge movenode uses the cooras action to read out 
the edge’s current coordinates and replace either the first two or last two 
coordinates to reflect the node’s new location. 

The two new bindings apply to all items with the tag noae. When button 1 is 
pressed while the Control key is held, the pointer coordinates are stored in 
variables curx and cury. When the mouse is dragged with button | down 
while the Control key is held, the current item is moved by the amount the 
mouse has moved and new pointer coordinates are recorded. 

Note that there is an additional widget binding for the <controi-ButtonPress -1> 
event as well, which provides a script that does nothing. If you omitted this 
binding, a <controi-suttonpress-1> event would be presented to the canvas 
widget after the canvas item binding is processed. Without an exact binding 
match, Tk would look for the best match and find and execute the 
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<ButtonPress-1> binding on the canvas. As a result, every time you tried to 
move a node, you’d also end up creating a new node, which is not desired 
behavior. 


23.4 Canvas Scrolling 


Canvases support vertical and horizontal scrolling in the standard fashion 
for Tk widgets (see Section 18.9). However, if a canvas is scrolled, the 
coordinates in the canvas window are not the same as the coordinates on the 
logical surface of the canvas. To handle this situation canvases provide 
additional widget command actions for translating from screen to canvas 
coordinates. 

Since the canvas can be considered a virtual sheet at least 32,000 by 32,000 
pixels in size, the scrolling is not enabled until a scroll region is defined. 
This limits the area that the scrollbars use as the visible region of the 
canvas. The scroll region is defined by setting the canvas -scroliregion 
option. The value is a list of four numbers defining the left, top, right, and 
bottom bounds of the region, respectively. The canvas widget uses these 
bounds to set the scrollbar range (see Figure 23.3). The most common way 
to set the scroll region is to use the canvas pox subcommand to obtain the 
bounding region of all items currently on the canvas: 


.c configure -scrollregion [.c bbox all] 


Figure 23.3 Canvas scroll region 
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Objects 


Scroll region 


Note 


Any time you create, delete, move, scale, or otherwise modify items on 
the canvas, you could end up modifying the bounding region of all 
items on the canvas. 


Now that the canvas can be scrolled to view different regions of the virtual 
canvas, translating mouse x- and y-coordinates to canvas coordinates is 
necessary in order to identify locations in the canvas for the current view. 
Mouse x- and y-coordinates are measured relative to the window’s upper 
left origin. If the canvas is scrolled, the upper left corner of the window no 
longer represents the 0, o coordinate on the canvas. The canvas widget’s 
canvasx aNd canvasy Subcommands translate the window-relative coordinates 
into the canvas coordinates based on the current scroll positions. 

For example, to enable scrolling of the graph application presented in 
Section 23.3, you would need to modify all of the mouse event-binding 
scripts to translate from window-relative mouse coordinates to canvas 
coordinates, such as 
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bind .c <ButtonPress-1> { 
mkNode [.c canvasx %x] [.c canvasy ty] 
} 


23.5 PostScript Generation 


Canvases can generate Encapsulated PostScript descriptions of their 
contents for printing and insertion into other documents. Use the postscript 
scommand to output the contents of a canvas widget to PostScript; for 
example: 


.c postscript -file canvas.eps 


This command writes the contents of the canvas widget .- into a file named 
canvas.eps. If you don’t provide the -+i1e option, the PostScript data becomes 
the return value of the command. 

The postscript Subcommand has a number of options to configure the 
PostScript results. See the canvas reference documentation for more 
information. The pagatc1 extension, available at nttp://paratci.berlios.de/, 
allows you to output the contents of a canvas widget to a PDF file. Many 
users find the PDF format easier to work with than Encapsulated PostScript. 


544 


24. The Text Widget 


This chapter describes Tk’s text widget, which displays one or more lines 
of text. The text widget can also display embedded images and widgets. The 
text widget can be used to display text, provides the ability to edit text, and 
even presents an interface for interacting with HTML or other tagged text. 


24.1 Text Widget Basics 


You create a text widget with the tex: command: 
text widgetName ?option value ...? 


The text widget supports many common widget options, such as -packgrouna, - 
foreground, and -font, Which determine the default settings of the text 
displayed; additional options specific to the text widget, such as -tabs and - 
wrap, provide default tab stops and line-wrapping settings. As you will see in 
Section 24.4, all of these settings can be overridden for particular 
characters by creating and applying tags. The text widget also supports - 
height and -wiath options for the height in lines of text and the width in 
characters; of course, the geometry manager used to display the canvas may 
override the requested size (as discussed in Chapter 21). The -undo option 
turns support for undo operations on or off, as described in Section 24.8. 
Text widgets also support vertical and horizontal scrolling in the standard 
fashion for Tk widgets (see Section 18.9). See the text widget reference 
documentation for a complete description of supported options. 
The basic text widget subcommands for manipulating text content are as 
follows: 

® widget delete indexl ?index2 ...? 
Deletes a range of characters from the text, starting with the character at 
index1 up to but not including the character at inaex2. If only inaexi 1s 
specified, that single character is deleted. Multiple ranges may also be 
specified. 

° widget get ?-displaychars? ?--? indexl ?index2 ...? 
Returns a range of characters from the text, up to but not including the 
character at inaex2. If only inaexi 1s specified, it returns that single character. 
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Multiple ranges may also be specified. Characters hidden with the -e1ide 
option are returned unless -aispiaychars 18 specified. 

© widget insert index chars ?tagList chars tagList ...? 
Inserts the string cnars just before the character at index, optionally applying 
the tags listed in tagrist to the characters. Multiple strings and tags may be 
provided for insertion. 


° widget replace indexl index2 chars ?tagList chars 


tagList ...? 
Deletes a range of characters from the text, starting with the character at 
index1 up to but not including the character at inaex2, replacing them with the 
string chars and optionally applying the tags listed in tagrise to the characters. 
Multiple strings and tags may be provided for insertion. 
Each line of text contained in a text widget must be terminated with a 
newline character. This is quite handy when reading text files and 
displaying their contents in a text widget. Depending on the -wrap settings that 
apply to the text, a single logical line might be wrapped visually in the text 
widget display, or it might be truncated and require horizontal scrolling to 
view the portions not visible. 
As an example, the following script creates a text widget with an associated 
scrollbar and reads a file into the text widget: 


# text: read a file into a text widget 


text .text -relief raised -bd 2 \ 
-yscrollcommand {.scroll set} 
scrollbar .scroll -command {.text yview} 
grid .text -row 0 -column 0 -sticky nsew 
grid .scroll -row 0 -column 1 -sticky ns 
proc loadFile {file} { 
.text delete 1.0 end 
set £f [open $file] 
.text insert end [read $f] 
close Sf£ 
} 
loadFile $tk_library/demos/README 


The first group of lines in the script creates a text widget and a scrollbar, 
grids them side by side in the main window, and sets up connections 
between the text and the scrollbar. The next part of the script defines and 
calls the procedure icaariie, Which opens a file, reads its content, and inserts 
the content at the end of the text widget. The .text aeiete Command iN toaarile, 
which deletes all of the text in the widget, isn’t necessary in this example 
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since the new widget is already empty. However, it allows icaariie to be 
invoked again later to replace the contents of the widget with a new file. 
After the script has completed, the screen should look like Figure 24.1 
(assuming that your system has the standard Tk widget demos, which are 
part of a standard Tk distribution). 


Figure 24.1 A text widget and associated scrollbar 


This directory contains a collection of programs to demonstrate 

the features of the Tk toolkit. The programs are all scripts for 
"wish", @ vindoving shell. If vish has been installed on your path 
then you can invoke any of the programs in this directory just 

by typing its file name to your command shell under Unix. Otherwise 
invoke wish with the file as its first argument, é.g., "wish hello”. 
The rest of this file contains 4 brief description of each program. 
Files vith names ending in ".tcl” are procedure packages used by one 
Or more of the demo programs; they can't be used as programs by 
themselves so they aren't described belov. 


hello - Creates a single button: if you click on it, a message 
is typed and the application terminates. 


widget - Contains a collection of demonstrations of the widgets 
currently available in the Tk library. Most of the .tcl 
files are scripts for individual demos available through 
the "widget" program. 


A simple Tk-based vrapper for the "xset”" program, vhich 
allovs you to interactively query and set various X options 
such as mouse acceleration and bell volume. Thanks to 
Pierre David for contributing this example. 


The default bindings for text widgets allow you to manipulate the text in a 
number of ways: 
¢ You can scroll the text with the scrollbar or by scanning with mouse 
button 2 in the text. 
* You can edit the text; for example, click with mouse button | to set the 
insertion cursor, then type new characters. 
* You can select information by dragging with mouse button | and then 
copying the selection into other applications. 
See the reference documentation for text widgets for complete information 
on the default bindings. 


24.2 Text Indices and Marks 


Many of the text widget commands require you to identify particular places 
in the text. For example, the insert action in the script from Section 24.1 
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specified ena as the place to insert the text read from the file. A position 
specifier in a text widget is called an index; it can take any of several forms. 
The simplest form for an index is two numbers separated by a dot, such as 
2.3. The first number gives a line number and the second number gives a 
character index within a line. The characters within a line are numbered 
starting with 0, as is common in Tcl; however, the lines are numbered 
starting with 1, so as to be compatible with most other programs that 
manipulate text files. If the character index is the string ena, as in 5.ena, it 
refers to the newline character terminating the line. The index ena refers to 
the end of the file, and an index in the form ex,», where x and y are numbers, 
refers to the character closest to the pixel at location «, y in the window. 

You can also use symbolic names for positions in a text; these symbolic 
names are called marks. For example, the command 


.text mark set first 2.3 


sets a mark named first to refer to the gap between character 3 of line 2 and 
the character just before it. In the future you can refer to the character after 
the mark as first instead of 2.3. The mark continues to refer to the same 
logical position even if characters are added to or deleted from the text. For 
example, if you delete the first character of line 2, first becomes 
synonymous with index 2.2 instead of 2.3. 

Each mark also has a “gravity,” which is either ieft or right. The gravity for 
a mark specifies what happens to the mark when text is inserted at the point 
of the mark. If a mark has left gravity, it is treated as if it were attached to 
the character on its left, so the mark remains to the left of any text inserted at 
the mark position. If the mark has right gravity, which is the default, new text 
inserted at the mark position appears to the left of the mark (so that the mark 
remains rightmost). You can query or set the gravity of a mark with the marx 
gravity SUubcommand, such as in this example, which sets the gravity of the 
mark first tO 1eft: 


.text make gravity first left 


Two marks have special meaning in text widgets. The insert mark identifies 
the location of the insertion cursor; if you modify insert, Tk displays the 
insertion cursor at the new location. The second special mark 1s current, 
which Tk updates continuously to identify the character underneath the 
mouse pointer. 

Indices can also take more complex forms consisting of a base followed by 
one or more modifiers. For example, consider the following command: 
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.text delete insert "insert + 2 chars" 


Both of the indices for this aeiete command use insert aS a base, but the 
second index also has a modifier + 2 chars, which advances the index by two 
characters over its base value. Thus, the command deletes the two 
characters just to the right of the insertion cursor. Some other examples of 
modifier usage are first 1ineena, which refers to the newline at the end of the 
line containing the mark ¢irst, and insert wordstart, Which refers to the first 
character of the word containing the insertion cursor. 


24.3 Search and Replace 


The text widget supports a search Subcommand and a repiace Subcommand. 
The search Subcommand scans through the text looking for exact match strings 
or regular expression pattern matching. It has the ability to return the next 
match after a given starting point or returning all the matching locations. The 
replace SUbCommand combines delete and insert operations into a single 
command. 

Here is a procedure that uses marks and other indices to provide a general- 
purpose searching facility for text widgets: 


proc forAllMatches {w pattern script} { 


set countList [list] 

set startList [$w search -all -regexp \ 
-count countList $pattern 1.0 end] 

foreach first $startList count ScountList { 


Sw mark set first $first 

Sw mark set last [Sw index "$first + $count chars"] 

uplevel 1 Sscript 

} 

The foraiimatches procedure takes three arguments: the name of a text widget, 
a regular expression pattern, and a script. It uses the text widget’s search 
subcommand to find all the starting indices for the text matching the pattern. 
The -count option returns a list of the number of characters for each match in 
the variable counttist. For each match, soraiimatches Sets the marks first and 
iast to the beginning and end of the range, then it invokes the script. For 
example, the following script prints out the locations of all instances of the 
word rx in the text: 
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forAllMatches .text Tk { 
puts "[{.text index first] --> [.text index last]" 
} 


16.31 

20.18 --> 20.20 
34.47 --> 34.49 

For each matching range the inaex subcommand is invoked for the first and 

1ast Marks; it returns numerical indices corresponding to the marks, which 

puts prints on standard output. As another example, you could clean up 

redundant «ne words in a text with the following script: 


forAllMatches .text "the the" { 
.text delete first "first + 4 chars" 


In this script the action taken for each range is to delete the first four 
characters of the range, which eliminates the redundant tne (this example 
works only if both tnes are on the same line). 

Because the text widget indices look like real numbers, there is a tendency 
to treat them as real numbers, but this can cause unexpected problems. For 
example, comparing two indices using a simple expression does not give 
correct results: 


.t mark x 3.37 
set x [.t index x] 
set mark_insert [.t index insert] 
if {$mark_x > $mark_insert} { 

puts “Insert is before mark x" 
} else { 

puts "Insert is after mark x" 
} 


In this example, if the insert mark was located at index 3.7, the code 
incorrectly reports that the insert mark was after the x mark. 

The text widget provides a compare Subcommand to perform index relational 
comparisons: 


widget compare index! op index2 


This compares the indices given by index: and inaex2 according to the 
relational operator given by op and returns : if the relationship is satisfied 
and o if it is not. op must be one of the operators <, <=, =-, >=, >, or :-. Here is 
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the correct way to compare the index values in the preceding example: 


if {[.t compare x > insert]} { 
puts "Insert is before mark x" 
} else { 
puts “Insert is after mark x" 


24.4 Text Tags 


Text tags provide a tagging mechanism similar to that of canvases except 
that text tags apply to ranges of characters instead of graphical items. Tags 
serve three purposes in the text widget. First, they are used to control the 
formatting of the characters, such as foreground and background color, font, 
spacing, and left and right margins. Second, they provide a way to manage 
the selection. Finally, they provide event bindings, turning plain text into 
active controls. 

A tag name can have any string value, and it can be applied to arbitrary 
ranges within the text. A single character may have multiple tags, and a 
single tag may be associated with many ranges of characters. For example, 
the command 


.text tag add the WholeEnchilada 1.0 1.end 


applies the tag thewnolernchilada to the first line of the text; the command 


.text tag remove wrd "insert wordstart" "insert wordend" 


removes the tag wra from all the characters in the word around the insertion 
cursor; and 


.text tag ranges hot 
=> 1.01.3 1.8 1.13 


returns a list of indices for the beginning and end of each range of characters 
tagged with not. In the preceding example the tag not 1s present on the 
characters at indices 1.0 through 1.2 and 1.8 through 1.12. 

Using the ¢oraiimatches procedure from Section 24.3, let’s demonstrate how 
tags can be used to control the formatting of text. The following script 
changes all instances of the word rx so they are drawn with a larger font, a 
darker background color, and a raised relief: 
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forAllMatches .text Tk { 
.text tag add big first last 
} 


.text tag configure big -background "cornflower blue" \ 
-font {Helvetica 24} \ 
-borderwidth 2 
-relief raised 


The results are shown in Figure 24.2. 


Figure 24.2 Using tags to format characters in a text widget 


This directory contains a collection of programs to demonstrate 


the features of the toolkit. The programs are all scripts for 
"wish", a vindoving shell. If wish has been installed on your path 
then you can invoke any of the programs in this directory just 

by typing its file name to your command shell under Unix. Otherwise 
invoke wish with the file as its first argument, e.g., “wish hello”. 
The rest of this file contains a brief description of each program. 
Files with names ending in ".tcl” are procedure packages used by one 
or more of the demo programs; they can't be used as programs by 
themselves so they aren't described below. 


hello - Creates a single button: if you click on it, a message 
is typed and the application terminates. 


widget - Contains a collection of demonstrations of the widgets 
currently available in the library. Most of the .tcl 


files are scripts for individual demos available through 
the "widget” program. 


& simple i... wrapper for the "xset" program, vhich 


One special tag, sei, is used to manage the selection and has these special 
characteristics: 

¢ Whenever characters are tagged with sei, the text widget claims 
ownership of the selection. 

¢ Attempts to retrieve the selection are serviced by the text widget, 
returning all the characters with the sei tag. 

* If the selection is claimed away by another application or by another 
window within the current application, the s-1 tag is removed from 
all characters in the text. 

¢ Whenever the sei tag range changes, a virtual event <<selection>> 1S 
generated. This is discussed more in Section 24.5. 

¢ The sei tag cannot be deleted with the tag ae1ete command. 

¢ The sei tag is not shared with peer text widgets. Instead, each text 
widget maintains its own sei tag. Peer text widgets are discussed in 
Section 24.9. 
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24.4.1 Tag Options 


There are almost two dozen tag options that can be grouped into three 
categories: visibility, which allows for the hiding of text; formatting, which 
affects the look of the characters such as font, size, and color; and layout, 
which affects the placement of the characters on the display. 
The only visibility tag option is -ciiae, which takes a Boolean value. If this 
value is true for a tag, the characters to which this tag is applied are not 
displayed by the text widget. By default, other text subcommands still apply 
to the elided characters, though many of them have an option to ignore 
elided characters if desired. 
Formatting tag options are similar to named character styles in a word- 
processing application in that they affect the appearance of individual 
characters. Thus, a single line of text could have several tags applying 
formatting to groups of characters, achieving a mix of colors, fonts, sizes, 
and so on. The following formatting tag options are available: 
® -pbackgrouna—the background color of the characters 
* -pgstipple—a Stipple pattern for the background 
® -borderwidth—the width of the text border, as a screen distance 
* -fgstipple—a Stipple pattern applied to the characters 
* -font—the character font 
® -foregrouna—the color of the characters 
* -offset—the number of pixels by which the text’s baseline should be 
offset vertically from the overall line’s baseline; a positive value 
raises the text to achieve a superscript effect, and a negative value 
lowers the text to achieve a subscript effect 
* -overstrike—a Boolean specifying whether or not to draw an 
overstrike line through the middle of the characters 
* -relier—the three-dimensional border style for the text 
* -underline—a Boolean specifying whether or not to underline the 
characters 
The layout tag options are somewhat analogous to named paragraph styles in 
a word-processing application, in that they determine display settings that 
affect entire display lines. The layout tag options differ from the formatting 
tag options in that they apply only if they occur on a tag applied to the first 
nonelided (visible) character on a display line. Because it is difficult to 
predict which characters might appear at the beginning of display lines, the 
common practice when using these tag options 1s to apply the relevant tag to 
the entire logical line of characters. The following layout tag options are 
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available: 
* -justity—how to justify display lines; one of tert, right, OF center 
* -1margini—the indent from the left side of the widget for the first 
display line, expressed as a screen distance 
* -1margin2—the indent from the left side of the widget for the second 
and subsequent display lines, expressed as a screen distance 
* -rmargin—the indent from the right side of the widget for display lines, 
expressed as a screen distance 
-spacingi—the amount of extra space to leave above the first display 
line, expressed as a screen distance 
-spacing2—the amount of extra space to leave above the second and 
subsequent display lines, expressed as a screen distance 
-spacing3—the amount of extra space to leave below the last display 
line, expressed as a screen distance 
* -tabs—a list of tab stops, as discussed below 
* -tabstyle—the tab style, as discussed below 
* -wrap—wWwhether to wrap at word boundaries (wora), at any character 
(char), or not at all (none) 
Tab stops for tags as well as the widget as a whole are set with the -tavs 
option, which accepts a list of tab stops expressed as screen distances from 
the left edge of the widget. After each position element in the list, you have 
the option of providing one of the following keywords as another element to 
set the justification of that tab stop: 1er+ (the default), rignt, center, OF numeric. 
ieft Causes the text following the tab character to be positioned with its left 
edge at the tab position, rignt means that the right edge of the text following 
the tab character is positioned at the tab position, and center means that the 
text 1s centered at the tab position. numeric means that the decimal point in the 
text 1s positioned at the tab position; if there is no decimal point, the least 
significant digit of the number is positioned just to the left of the tab 
position; if there is no number in the text, the text is right-justified at the tab 
position. For example, 


-tabs {2c left 4c 6c center} 


creates three tab stops at 2-centimeter intervals; the first two use left 
justification and the third uses center justification. 

If the list of tab stops does not have enough elements to cover all of the tabs 
in a text line, Tk extrapolates new tab stops using the spacing and alignment 
from the last tab stop in the list. If no -tass option is specified, or if it is 
specified as an empty list, Tk uses default tabs spaced every eight (average 
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size) characters. 

The -tabstyie Option specifies how to interpret the relationship between tab 
stops on a line and tabs in the text of that line. The value must be tabuiar (the 
default) or wordprocessor. If the tab style 1s tabuiar, the nth tab character in the 
line’s text is associated with the »th tab stop defined for that line. If the tab 
character’s x-coordinate falls to the right of the sth tab stop, the text widget 
displays a gap of a single space as a fallback. If the tab style 1s woraprocessor, 
any tab character being laid out uses the first tab stop to the right of the 
preceding characters already laid out on that line. 


24.4.2 Tag Priorities 


As mentioned previously, a range of characters can have multiple tags 
applied to it. If two or more tags specify options that conflict, the options of 
the tag with the highest priority are used. If a particular display option has 
not been specified for a particular tag, or if it is specified as an empty 
string, that option is not used; the next-highest-priority tag’s option is used 
instead. If no tag specifies a particular display option, the default style for 
the widget is used. 

When a new tag is defined, it is initially assigned a priority higher than that 
of any existing tags defined for the text widget. You can change the priority 
of a tag with the tag iower and tag raise Subcommands. For example, the 
following command takes the important tag and raises it to the highest tag 


priority: 
.text tag raise important 
This next example lowers the priority of 51a to just lower than the urx tag: 


.text tag lower bold URL 


24.4.3 Tag Bindings 


The text widget allows you to associate bindings to tags with the tag bina 
subcommand. You can use bindings to make portions of text “active” so that 
they respond to mouse, keyboard, <znter>, <teave>, Or virtual events. Among 
other things, this enables you to implement hypertext effects. For example, 
the following bindings cause all the 7x words to turn green whenever the 
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mouse passes over any one of them: 


.text tag bind big <Enter> { 


} 


.text tag bind big <Leave> ;{ 


1 
I 


.text tag configure big -background SeaGreen2 


f 


.text tag configure big -background Bisque3 


The following binding causes the text widget to reload itself with the Tk 


demo’s zz 


ADM 


= file when the user holds the Control key while clicking button 


1 on any of the rx words: 


- text 


tag bind big <Control-Button-1> { 


.text delete 1.0 end 


loadFile $tk_library/demos/README 


Note 


Cc 


Keyboard events trigger a tag binding only when the mouse cursor is 
within the tagged region containing the binding. The insert cursor does 
not have to be within the tagged region. 


It is possible for multiple bindings to match a particular event, for example, 
if you’ve created bindings for multiple tags and then applied some 
combination of those tags to a section of text. When this occurs, all of the 
matching bindings are invoked, in order from lowest-priority to highest- 
priority tag. If there are multiple matching bindings for a single tag, only the 
most specific binding is invoked. A continue command in a binding script 
terminates that script, and a preax command terminates that script and skips 
any remaining scripts for the event, just as for the bina command. 


Note 


If bindings have been created for a text widget using the bina command, 
they are invoked in addition to bindings created for the tags using the 
tag bina SUbCommand. The bindings for tags are invoked before any of 
the bindings for the widget as a whole. 
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24.5 Virtual Events 


The text widget generates two virtual events. You can create bindings for 
these events to handle them in any way you like. Often they are used to 
dynamically enable or disable other interface features to behave in a 
context-sensitive fashion. 

The <<modifea>> event 1s associated with the undo mechanism described in 
Section 24.8. This feature requires the -unao option to be set to true (:) to be 
enabled. The <<moairica>> event is generated the first time a change is made to 
the text widget’s content after the widget’s modified flag is cleared. The 
event 1s also generated when this flag is cleared, either by the eait undo 
widget command or the explicit cait moaitiead command. This event is often 
used to enable a “save” feature only if the widget’s contents have been 
modified since the last save operation. An example similar to this is shown 
in Section 24.8. 

The <<selection>> event is generated whenever the widget’s selection 
changes. It is often used to enable interface features like cut and copy only if 
the sei tag is applied to any characters, and to disable the features 
otherwise. An example of this is shown in Chapter 22. 


24.6 Embedded Windows 


In addition to text, a text widget can contain any number of widgets. These 
are called embedded windows, and can be instances of any widget class. 
Figure 24.3 shows the Tk widget demo embedded window example. 


Figure 24.3 Embedded button and canvas widgets in a text widget 
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i @ © @ Text Demonstration - Embedded Windows and Other Features 


a 


Or, here is another example. if you { Click Here } acanvas displaying an x-y plot 
will appear right here. 


A Simple Plot 


“0 10 20 30 40 50 60 70 80 90 100 


You can drag the data points around with the mouse, or you can click here to 


( Delete ) the plot again. 


| ICh See Code | X Dismiss 


Widgets are inserted inline with the text and are subject to the same 
padding, spacing, justification, and wrapping rules that apply to the text as if 
each widget were a single character, albeit a very large character. 
The text widget is acting as a geometry manager for the embedded windows, 
so the widgets should be created as children of the text widget. Embedded 
windows are inserted into a text widget using the window create subcommand. 
The following code shows how this is done, and the result is shown in 
Figure 24.4: 

$t insert end "You can click on the first button to " 

button $t.on -text "Turn On" -command "textWindOn $w" 

$t window create end -window §$t.on 


St insert end " horizontal scrolling, which also turns" 
$t insert end " off word wrapping." 


Figure 24.4 Embedding an existing button into a text widget 
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You can click on the first button to ( Turn On_) horizontal scrolling, which also 


turns off word wrapping. 


Another way to insert widgets is to use the -create option instead of the - 
window Option. The -window option requires that the widget be constructed 
separately. The -create option is supplied a script that is evaluated by the 
text widget when it needs the embedded window. Since embedded windows 
cannot be shared between peer text widgets, it is necessary to create unique 
widgets for each peer. The create script is typically used to accomplish this. 
The following code shows how this is done, and the result is shown in 


Figure 24.5: 


St insert end "Or, here is another example. If you " 
$t window create end -create { 
button $W.click -text "Click Here" \ 
-command "“textWindPlot +W" 
} 
$t insert end " a canvas displaying an x-y plot will” 
$t insert end “ appear right here." 


Figure 24.5 Using a create script to create an embedded button 


Or, here is another example. If you | Click Here ) a canvas displaying an x-y plot 


will appear right here. 


24.7 Embedded Images 


Another type of item that can be added to a text window is an image. Images 
can be inserted into the text using the image create Widget command and can 
appear inline with the text. This can be useful for inserting special-purpose 
markers, emoticons, or even photographs. The following script 
demonstrates inserting a specialized stop sign image used as a marker in the 
text; the result is shown in Figure 24.6. Notice that instead of deleting the 
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<stop> text and replacing it with the image, a tag is applied instead with the - 
elide Option set to true. This makes it possible to retrieve the original text 
with the get subcommand, or through the user doing a copy-and-paste 
operation involving the text. 


Figure 24.6 Example of using a stop sign as an embedded image 


Dear Mom & Dad, 


School is going well sto?) 
Running low on funds, please send cash st07) 


Love, Your Son st0P 
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text .edit -yscrollcommand ".vsb set" \ 

-xscrollcommand ".hsb set" -wrap none 
scrollbar .vsb -command “.edit yview" -orient vertical 
scrollbar .hsb -command ".edit xview" -orient horizontal 


set letter {Dear Mom & Dad, 


School is going well <STOP> 
Running low on funds, please send cash <STOP> 
Love, Your Son <STOP> 


,eadit insert end $letter 


set stopImage [image create photo \ 
-file stop_sign.gif] 


,edit tag configure symbol -elide 1 


proc insertStops {w} { 
foreach ix [$w search -all -forward "<STOP>" 1.0) { 
Sw tag add Six "$ix + 6 char" 
$w image create $ix -image $::stopImage 


} 


grid .edit -row 0 -column 0 -sticky nsew 
grid .vsb -row 0 -column 1 -sticky ns 
grid .hsb -row 1 -column 0 -sticky ew 
grid rowconfigure . 0 -weight 1 

grid columnconfigure . 0 -weight 1 


insertStops .edit 


Images are subject to the same wrapping and justification rules as regular 
text. In the following example, nothing but images are placed in the text 
widget, and the text widget is used like a geometry manager to lay out the 
photos in a reasonably nice fashion: 
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text .t -yscrollcommand ".vsb set" 
scrollbar .vsb -command ".t yview" 


grwea st -row 0 -column 0 -sticky nsew 
grid .vsb -row 0 -column 1 -sticky ns 
grid rowconfigure . 0 -weight 1 

grid columnconfigure . 0 -weight 1 


foreach f [lsort -dictionary [glob *.gif]] { 
set img [image create photo -file $f] 
.t image create end -image $img -padx 2 -pady 2 
.t insert end " " 


24.8 Undo 


The text widget has an unlimited undo/redo mechanism that is enabled by 
setting the widget’s -unao option to 1. The mechanism records each insert and 
delete action on a stack. These actions can be reversed by issuing the ecait 
undo SUbcommand. Boundaries are inserted between edit actions to define 
groups of actions. These groups are used to define compound edit actions 
that can be undone in a single step. The -autoseparators option, when enabled, 
automatically inserts boundaries to group sequences of inserts or deletes. 
You can add boundaries to the stack explicitly using the eait separator 
subcommand. This can be useful if you want greater control of the undo 
granularity in your application. 

The text widget also keeps track of modifications by way of the modify flag 
and the <<modifiea>> virtual event. The modify flag is set to true and the 
virtual event is triggered after any change (insert or delete) is made to the 
data since the last time the flag was cleared. This flag is useful for 
determining if the widget’s content needs to be saved, or for enabling or 
disabling buttons, like a save button or undo button. The flag can be read 
and set using the eait modified Widget command. 

The following code adds undo and redo buttons to the example from earlier 
in the chapter: 
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# text: read a file into a text widget, with undo 


text .text -relief raised -bd 2 \ 
-yscrollcommand ".scroll set" \ 
-undo 1 

scrollbar .scroll -command ".text yview" 


proc loadFile file { 
-text delete 1.0 end 
set £ [open $file] 
-text insert end [read $f] 
close $f 


# Mark as not being changed 
.text edit modified 0 


} 


proc undoText {tw} { 
catch {$tw edit undo} 
} 


proc undoText {tw} { 
catch {$tw edit undo} 
I 


proc dataModified {tw} { 
if {[$tw edit modified] } { 
.undo configure -state normal 
} else { 
-undo configure -state disabled 
} 


} 


frame .toolbar 
button .undo -text "Undo" -command {undoText .text} 


bind .text <<Modified>> { 
dataModified .text 
} 


pack .undo -in .toolbar -side left 

pack .toolbar -side top -expand 1 -fill x 
pack .scroll -side right -fill y 

pack .text -side left 


loadFile README 
Notice that we modified the icaariie function to clear the modified flag after 


loading a file by adding the line 
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.text edit modified 0 


In addition, we added the -unao 1 option to the text widget command and 
packed the widgets in the proper order. Figure 24.7 shows the resulting 
window when the application is first launched. 


Figure 24.7 Updated text window with Undo button 


README: 


This is the §.5a6 source distribution, 


Tkis also available through NetCVS: 
hitp: //tel sourceforge.net/ 


You can get any source release of frorn the file distnbutions 
link at the above URL. 


RCS: @(#) Hd: README,» 1.58 2006/10/23 19:42:18 dap Exp $ 


1. Introduction 
2 Documentation 


3. Compiiing and installing Tel 


4. Development tools 


With these additions, the moment a change is made in the text widget, by 
typing or deleting something, the Undo button is enabled, as shown in Figure 
24.8. You can then reverse the edits simply by pressing the Undo button. 
Once the undo stack is exhausted, the Undo button is disabled automatically, 
as shown in Figure 24.9. 


Figure 24.8 An edit automatically enables the Undo button. 


hi some text. 


README: 


This is the 8.5a6 source distribution. 
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Figure 24.9 Exhausting the undo stack disables the Undo button. 


Lins 


README 
This is the 8.5a6 source distribution. 
24.9 Peer Text Widgets 


The peer text widget command is used to create duplicate text widgets that 
share the same text data. Any changes made in one text widget immediately 
appear in its peer widgets. This command is useful for creating split views, 
common in most modern text editors. Peer widgets share all text, images, 
and tags. They do not share embedded windows, the tag sei, or the marks 
insert aNd current. The following script shows an example of creating two 
text widgets as peers. Any change you make in one is reflected immediately 
in the other, as is shown in Figure 24.10: 
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panedwindow .pane -orient vertical 
frame .tf ;# Top Frame 
frame .bf ;# Bottom Frame 
text .text -relief raised -bd 2 \ 
-yscrollcommand ".scroll set" \ 
-undo true -autoseparators true \ 
-height 12 
.text peer create .text2 -relief raised -bd 2 \ 
-yscrollcommand ".scroll2 set" \ 
-undo true -autoseparators true \ 
-height 12 
scrollbar .scroll -command ".text yview" 
scrollbar .scroll2 -command ".text2 yview" 
pack .scroll -in .tf -side right -fill y 
pack .text -in .tf£ -side left -fill both -expand yes 
pack .scroll2 -in .bf -side right -fill y 
pack .text2 -in .bf -side left -fill both -expand yes 
-_pane add .tf -sticky nsew 
._pane add .bf -sticky nsew 
pack .pane -side top -fill both -expand 1 
loadFile README 


Figure 24.10 A split-pane view using peer text widgets 


For details on features, incompatibilities, and potential problems with 
this release, see the /Tk 8.5 Web page at 


http: //www.tcl.tk/software/tcltk/8.5.html 


or refer to the “changes” file in this directory, which contains a 
historical record of all changes to Tk. 


Tk is maintained, enhanced, and distributed freely by members of the 
community. The home for Tk sources and bug database is on 


README: Tk 
This is the Tk 8.5a6 source distribution. 


/Tk is also available through NetCvs: 
http://tcl.sourceforge.net/ 


You can get any source release of Tel from the file distributions 
link at the above URL. 


RCS: @(#) SId: README,v 1.46 2006/10/23 19:46:13 dgp Exp $ 


1. Introduction 


Peer text widgets are true peers. This means that destroying the original text 
widget does not affect the existing peer widgets. The text widget content is 
not destroyed until all the peer text widgets are destroyed. Peers can also 
create other peers. The peer names Subcommand can be used to find the 
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widget path names of all the peer widgets for a given text widget. 
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25. Selection and the Clipboard 


The selection is a mechanism for passing information between widgets and 
applications. The user first selects one or more objects in a widget, for 
example, by dragging the mouse across a range of text or clicking on a 
graphical object. Once a selection has been made, the user can invoke 
commands in other widgets to retrieve information about the selection, such 
as the characters in the selected range or the name of the file containing the 
selection. In today’s windowing environments there are two different 
selection models, the selection owner model and the clipboard model. 

The selection owner model is used in the X Window System. There is a 
single owner of the selection at any given time. The widget containing the 
selection and the widget requesting it can be in the same or different 
applications. The receiving application or action can query the selection 
owner and obtain the information about the selection. 

In the clipboard model, which is the model used in Microsoft Windows and 
Mac OS X as well as the X Window System, a global, virtual storage 
device is used called a clipboard. Selected items are copied to the 
clipboard, where they can be retrieved later by another widget or 
application. This model uses selection also, but here the ownership is 
confined to the current active window. 

The selection, like the clipboard, is most commonly used to copy 
information from one place to another. Tk widgets have default bindings to 
do these common selection and clipboard operations, so you rarely need to 
manage the selection or clipboard explicitly in your applications. However, 
if your application needs to provide custom selection or clipboard handling, 
you can implement this functionality with the setection amd clipboara 
commands. The seiection command is used to manage the selection 
ownership and provide access to selection data. The ciippoara command 
manages the clipboard, though the se1ection command can be used for that 
purpose as well. 


25.1 Commands Presented in This Chapter 


This chapter discusses the following commands for managing the selection: 


® selection clear ?-displayof window? ?-selection selection? 
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Clears or “unselects” the current selection. window defaults to . and selection 
defaults to primary. 

® selection get ?-displayof window? ?-selection selection? 

?-type type? 

Retrieves the selection according to selection and type. window defaults to ., 
selection defaults to primary, and type defaults to srrinc. 

® selection handle ?-selection selection? ?-type type? 

?-format format? window script 

Creates a handler for selection requests. script 18 evaluated whenever the 
selection 18 Owned by window and someone attempts to retrieve it in the form 
given by type. selection defaults to primary, and format and type default to srainc. 
See the text and the reference documentation for more information. 


® selection own ?-displayof window? ?-selection selection? 


Returns the current owner of se1ection, or an empty string if no window owns 
selection. window defaults to . and selection defaults to primary. 
© selection own ?-command script? ?-selection selection? 
window 
Claims ownership of setection fOr window. If script 18 specified, it is executed 
when window loses the selection. seiection defaults to primary. 


® clipboard clear ?-displayof window? 


Claims ownership of the clipboard on window's display and removes any 
previous contents. window defaults to .. 

® clipboard append ?-displayof window? ?-format format? 

?-type type? ?--? data 

Appends aata to the clipboard on window's display in the form given by type 
with the representation given by format and claims ownership of the 
clipboard on windows display. winaow defaults to ., and format and type default 
tO sTRING. 

* clipboard get ?-displayof window? ?-type type? 
Retrieves data from the clipboard on windows display. type specifies the form 
in which the data is to be returned. window defaults to . and type defaults to 


STRING. 


25.2 Selections, Retrievals, and Types 


In the selection owner model, when a user selects information in a window, 
the window acquires selection ownership. By convention, the primary 
selection is used, though other selections are supported under the X Window 
System. It is possible for multiple disjointed objects to be selected 
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simultaneously within a widget (for example, three different items in a 
listbox or several different polygons in a drawing window), but usually the 
selection consists of a single object or a range of adjacent objects. When a 
window acquires ownership of the selection, any previous owner is notified 
that it has lost ownership of the selection. At any time, the selection owner 
may receive a request for the selection content in a particular format, and so 
the selection owner must arrange to service these requests until it loses 
ownership of the selection. 

In the clipboard model, the user selects some information in a window, and 
then explicitly requests that the data be copied to the clipboard. Clients can 
then use the crrpsoarp selection to request a copy of the data from the 
clipboard. 

When you retrieve the selection, you can ask for several different kinds of 
information, referred to as retrieval types, which are also known as targets. 
The most common type 1s srainc. In this case the contents of the selection are 
returned as a string. For example, if text 1s selected, a retrieval with type 
stainc returns the contents of the selected text; if graphics are selected, a 
retrieval with type srrinc could return some string representation for the 
selected graphics. If the selection is retrieved with type rrtz_name, the return 
value could be the name of the file associated with the selection. If type tive 
is used, the return value could be the number of the selected line within its 
file. There are many types with well-defined meanings; refer to the X 
Consortium Standard Inter-Client Communication Conventions Manual 
(ICCCM) for more information. 

The command seiection get retrieves the selection. The type may be specified 
explicitly, or it may be left unspecified, in which case it defaults to srainc. 
For example, the following commands might be invoked when the selection 
consists of a few words on one line of a file containing the text of 
Shakespeare’s Romeo and Juliet: 


selection get 
= star-crossed lovers 

selection get -type FILE NAME 
=> romeoJuliet 


selection get -type LINE 


= 6 


These commands could be issued in any Tk application on the display 
containing the selection; they need not be issued in the application 
containing the selection. 

Not every widget supports every possible selection type. For example, if 
the information in a widget isn’t associated with a file, the rrtz_name type may 
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not be supported. If you try to retrieve the selection with an unsupported 
type, an error is returned. It is up to the selection owner to define the types 
supported for the selection and to perform the translation. Fortunately, every 
widget is supposed to support retrievals with type tarcers; such retrievals 
return a list of all the target forms supported by the current selection owner. 
You can use the result of a tarcers retrieval to pick the most convenient 
available type. For example, the following procedure retrieves the selection 
as PostScript if possible and as an unformatted string otherwise: 


proc getSelection {} { 
set types [selection get -type TARGETS] 
if {"POSTSCRIPT" in Stypes} { 
return [selection get -type POSTSCRIPT] 


te [selection get -type STRING] 
} 

Tk widgets always support the type sraivc. Tk widgets also support the 
following ICCCM types: MULTIPLE, TARGETS, TIMESTAMP, TK APPLICATION, and 
tx winpow, and on X Window Systems only, urrs strive. muttrete allows for the 
selection to include more than one item or block of text at a time. sazczrs 
gives the list of supported types. timestamp indicates when the selection 
occurred. The two TK types are specific to Tk applications and are 
discussed in the next section. 


25.3 Locating and Clearing the Selection 


Tk provides two mechanisms for finding out who owns the selection. The 
command selection own (with no additional arguments) checks whether the 
selection is owned by a widget in the invoking application. If so, it returns 
the path name of that widget; if there is no selection or it is owned by some 
other application, seiection own returns an empty string. 

The second way to locate the selection is with the retrieval types 
TK APPLICATION ANd Tx wrnpow. These types are both implemented by Tk and are 
available whenever the selection is ina Tk application. The command 


selection get -type TK_ APPLICATION 


returns the name of the Tk application that owns the selection (in a form 
suitable for use with the sena command, for example), and 


mei) 


selection get -type TK. WINDOW 


returns the path name of the widget that owns the selection. If the application 
that owns the selection isn’t based on Tk, it does not support the 
TK_ APPLICATION and TK wWINDow types, and the selection get Command returns an 
error. These commands also return errors if there is no selection. 

The selection clear command clears out any selection on the display of the 
application’s main window. It works regardless of whether the selection is 
in the invoking application or some other application on the same display. 
The following script clears out the selection only if it is in the invoking 
application: 


r 


if {[selection own] ne ""} { 
selection clear [selection own] 


} 
J 


25.4 Supplying the Selection with Tel Scripts 


The standard widgets such as entries and texts already contain C code that 
supplies the selection, so you don’t usually have to worry about it when 
writing Tcl scripts. However, it is possible to write Tcl scripts that supply 
the selection. For example, you might want a widget to support an additional 
type, such as rite nave, for better integration with other applications in your 
environment. 

The protocol for supplying the selection has three parts: 

1. A widget must claim ownership of the selection. This deselects any 
previous selection, then typically redisplays the newly selected 
material in a highlighted fashion. 

2. The selection owner must respond to retrieval requests by other 
widgets and applications. 

3. The owner may request that it be notified when it is deselected. 
Widgets typically respond to deselection by eliminating the 
highlights on the display. 

The next paragraphs describe two scenarios. The first scenario just adds a 
new type to a widget that already has selection support, so it deals only with 
the second part of the protocol. The second scenario implements complete 
selection support for a group of widgets that didn’t previously have any; it 
deals with all three parts of the protocol. 

Suppose that you wish to add a new type to those supported for a particular 
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widget. For example, text widgets contain built-in support for the sraine 
type, but they don’t automatically support the rrtz_namz type. You could add 
support for rtiz_vave retrievals with the following script: 


selection handle -type FILE NAME .t MyApp::getFile 
proc MyApp::getFile {offset maxBytes} { 
variable fileName 
set last [expr {Soffset + $maxBytes - 1}] 
return [string range $fileName Soffset $last] 
} 
This code assumes that the text widget is named .: and that the name of its 
associated file is stored in a namespace variable myapp: : filename. The setection 
nandile Command tells Tk to invoke wyapp::getriie Whenever .« owns the 
selection and someone attempts to retrieve it with type rriz_navz. When such 
a retrieval occurs, Tk takes the specified command (myapp::getrite in this 
case), appends two additional numerical arguments, and invokes the 
resulting string as a Tcl command. In this example a command such as 


MyApp::getFile 0 4000 


results. The additional arguments identify a subrange of the selection by its 
first byte and maximum length, and the command must return this portion of 
the selection. If the requested range extends beyond the end of the selection, 
the command should return everything from the given starting point up to the 
end of the selection. Tk takes care of returning the information to the 
application that requested it. In most cases the entire selection is retrieved 
in one invocation of the command; for very large selections, however, Tk 
makes several separate invocations so that it can transmit the selection back 
to the requester in manageable pieces. 

In the preceding example a new type was simply added to a widget that 
already provided some built-in selection support. If selection support is 
being added to a widget that has no built-in support at all, additional Tcl 
code is needed to claim ownership of the selection and to respond to 
deselect notifications. For example, consider a group of three radiobuttons 
named .a, .», and .- that have already been configured with their -variable 
and -vaiue options to store information about the selected button in a variable 
named wyapp::state. Suppose that you want to tie the radiobuttons to the 
selection, so that: (1) whenever a button becomes selected, it claims the X 
selection; (2) selection retrievals return the contents of myapp::state; and (3) 
when some other widget claims the selection away from the buttons, 
MyApp::state 18 Cleared and all the buttons become deselected. The following 
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code implements these features: 


selection handle -type STRING .a MyApp::getValue 

proc MyApp::getValue {offset maxBytes} { 
variable state 
set last [expr {Soffset + SmaxBytes - 1 
return [string range $state Soffset $la 

} 

foreach w {.a .b .c} 


$w config -command { 


selection own -command MyApp::selGone .a 


\ 
i 


proc MyApp::sel 
variable sta 
set state {} 


The selection hanale Command and the myapp::getvalue procedure are similar to 
the previous example: they respond to srrinc selection requests for .2 by 
returning the contents of the uyapp::state variable. The foreach loop specifies a 
-commana option for each of the widgets. This causes the selection own Command 
to be invoked whenever the user clicks on any of the radiobuttons, and the 
selection own COMmand claims ownership of the selection for widget .a (.a 
officially owns the selection regardless of which radiobutton the user 
selects, and it returns the value of myapp::state In response to selection 
requests). The selection own command also specifies that the procedure 
MyApp::selcone Should be invoked whenever the selection is claimed away by 
some other widget. myapp::se1Gone SetS myapp::state to an empty string. All of 
the radiobuttons monitor myapp:: state for changes, so when it gets cleared, the 
radiobuttons deselect themselves. 


25.5 The cripsoara Command 


The ciipboara Command interfaces with the windowing system clipboard. 
Data placed in the clipboard can be retrieved via the seiection command’s - 
selection CLIPBOARD Option or the ciipboara get command. Unlike what happens 
with the primary selection, data placed on the clipboard can be retrieved at a 
later time, independent of who owns the selection or if anything is selected 
at all. 

The clipboard is typically used to implement cut, copy, and paste operations 
for a window. The text widget provides a binding for the virtual <<copy>> 
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event that looks like this: 


proc tk_textCopy {w} 
if {! {catch {set data [$w get sel.first sel.last]}]} { 
clipboard clear -displayof Sw 
clipboard append -displayof Sw Sdata 
} 


} 
This function retrieves the selection from the text widget «, clears the current 
clipboard contents, and then copies the data to the clipboard with the 
clipboard append Command. The paste function performs the inverse operation: 
proc tk _textPaste {w} { 
if {![catch {clipboard get -display $w} sel]} { 
Sw insert insert Ssel 


} 


} 


Note 


This is a simplified version of the actual function for illustration only. 
The actual function also deletes the current selection in the target 
window and manages the edit history for the widget’s undo 
functionality. 


25.6 Drag and Drop 


Drag and Drop (DND) is the ability to select an object with the mouse and 
“drag” the object to a destination window. This action simplifies the 
common copy/paste or cut/paste actions in an application. Tk does not 
directly support this style of interaction, but intra-application DND 1s easily 
implemented using the se1ection OF clipboara command. The steps required for 
DND are as follows: 
1. On <suttonpress-1>, Mark the current window and location, assuming 
the mouse cursor is over an already selected object. 
2. On mouse motion, don’t start the “drag” operation until the mouse 
moves sufficiently from the starting point. Once the mouse has 
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moved far enough to indicate a “drag,” initiate the drag and provide 
feedback, for example, by changing the cursor. 

3. On <suttonrelease-1>, uSe the x- and y-coordinates relative to the 
display root to identify the window under the mouse (the winto 
containing Command can do this). 

4. Get the selection and insert the data at the location under the mouse 
as indicated by the ex and sy location in the target window. 

This simple approach works fine inside a Tk application, but what if you 
want to support DND between two applications, or between the application 
and the windowing system? There are extensions that implement standard 
DND protocols across multiple platforms, such as txmnn (see 
http://www. sourceforge. net/projects/tkand). This extension handles the sequence 
of operations for you so that the only code the application needs to provide 
is the code to perform the actual extraction of the selection and the insertion 
at the drop point. 
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26. Window Managers 


A window manager is a component of the windowing system whose main 
function is to control the arrangement and decoration of all the toplevel 
windows on each screen. In this respect it is similar to a geometry manager, 
except that instead of managing internal windows within an application, it 
manages the toplevel windows of all applications. The window manager 
allows each application to request particular locations and sizes for its 
toplevel windows, which users can override interactively. Window 
managers also serve several purposes besides geometry management: they 
add decorative frames around toplevel windows; they allow windows to be 
iconified and deiconified; and they notify applications of certain events, 
such as user requests to close the window. 

Some operating systems have just one desktop environment or window 
manager such as Microsoft Windows and Apple’s Mac OS X Aqua, 
whereas Linux and other Unix-based operating systems allow for the 
existence of many different window managers that implement different 
styles of layout, provide different kinds of decoration and icon management, 
and so on. Some examples include the GNOME and KDE desktop 
environments, along with the older CDE, or Common Desktop Environment. 
Only a single window manager runs on a display at any given time, and the 
user gets to choose which one. 

With Tk you use the wm command to communicate with the window manager. 
Tk implements the wm command so that any Tk-based application should 
work with any window manager without regard to the type of window 
manager or desktop environment currently in use. In order to create a well- 
behaved application on the desktop, your programs need to call the wm 
command to properly inform the window manager about window titles, 
icons, and so on. 


Note 


In general, an application can only send requests or provide hints to the 
window manager. The window manager is free to ignore or modify 
those requests and hints. For example, an application can request a 
certain size for its toplevel, but the window manager might enforce a 
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smaller size because of the available dimensions of the display, or the 
application might request a feature not implemented by the particular 
window manager. 


26.1 Commands Presented in This Chapter 


This chapter discusses the wm command for interacting with the window 
manager. In all of the following commands, window must be the name of a 
toplevel window. Many of the commands, such as wm aspect OF wm group, are 
used to set and query various parameters related to window management. 
For these commands, if the parameters are specified as null strings, the 
parameters are removed completely; if the parameters are omitted, the 
command returns the current settings for the parameters. 
® wm aspect window ?xThin yThin xFat yFat? 
Constrains the aspect ratio (width/length) of window to the values given. 


® wm attribute window ?attribute? ?value attribute value ...? 


Sets or queries the window-system-specific attributes. See Section 26.8 and 
the reference documentation. 


® wm client window ?name? 


Sets or queries the wa cirenr_macutne property for window, which gives the name 
of the machine on which winaow’s application is running. 


wm command window ?value? 
Sets or queries the wv commann property for window, which contains the 
command line used to initiate window's application. 


° wm deiconify window 


Arranges for window to be displayed in normal (noniconified) fashion. 


® wm focusmodel window ?model? 


Sets or queries the focus model for window, moder Must be active OF passive. 


* wm forget window 


Arranges for window to no longer be managed as a toplevel window by the 
window manager. 


° wm geometry window ?value? 


Sets or queries the requested geometry for window. value Must have the form 
=widthxheighttxty (any Of =, wiatnxheignht, OF +xty can be omitted). 

® wm grid window ?baseWidth baseHeight widthInc heightInc? 
Indicates that window 18 to be managed as a gridded window and also 
specifies the relationship between grid units and pixel units. See the 


reference documentation for more information. 
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® wm group window ? leader? 
Sets or queries the window group to which window belongs. 1eaaer must be the 
name of a toplevel window, or an empty string to remove window from its 
current group. 


° wm iconbitmap window ?-default? ?bitmap? 


Sets or queries the bitmap for winaow’s icon. If the -aefauit option 1s specified, 
the icon is applied to all toplevel windows (existing and future) to which no 
other specific icon has yet been applied. 


° wm iconify window 


Arranges for window to be iconified. 


° wm iconmask window ?bitmap? 


Sets or queries the mask bitmap for winaow’s icon. 


° wm iconname window ?string? 


Sets or queries the string to be displayed in window's 1con. 


°* wm iconphoto window ?-default? imagel ?image2...? 


Sets the title bar icon for window based on the named photo images. Multiple 
images are allowed to provide different image sizes. If the -cerauit option is 
specified, the icon is applied to all future toplevel windows as well. 


° wm iconposition window ?x y? 


Sets or queries the hints about where on the screen to display winaow’s 1con. 


° wm iconwindow window ?icon? 


Sets or queries the window to use as the icon for window. icon must be the path 
name of a toplevel window. 


° wm manage window 


Arranges for window to be managed as a toplevel window by the window 
manager. 


° wm maxsize window ?width height? 


Sets or queries the maximum permissible dimensions for wincow during 
interactive resize operations. 


° wm minsize window ?width height? 


Sets or queries the minimum permissible dimensions for window during 
interactive resize operations. 


® wm overrideredirect window ?boolean? 


Sets or queries the override-redirect flag for winaow. 


° wm positionfrom window ?whom? 


Sets or queries the source of the position specification for window. whom must 
be program OF user. 


® wm protocol window ?protocol? ?script? 


Arranges for script to be executed whenever the window manager sends a 
message tO window With the given protocol. protoco1 Must be the name of an atom 
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for a window manager protocol, such as wa petere_wrnvow. If script 18 an empty 
string, the current handler for protoco1 is deleted. If script 1s omitted, the 
current script for protoco: 18 returned (or an empty string if there is no 
handler for protoco1). If both protoco: and scripe are omitted, the command 
returns a list of all protocols with handlers defined for window. 


wm resizable window ?width height? 
Controls whether the user may interactively change the wiatn and the neignt of 
the window, according to the Boolean values given. 

° wm sizefrom window ?whom? 
Sets or queries the source of the size specification for window. whom must be 
program OF user. 


® wm state window ?newstate? 


Sets or queries the current state of window. The state can be one of normai, 
iconic, withdrawn, OF zoomed (Windows and Mac OS X only). 
° wm title window ?string? 
Sets or queries the title string to display in the decorative border for winaow. 
* wm transient window ?master? 
Sets or queries the transient status of window. master Must be the name of a 
toplevel window on whose behalf winaow is working as a transient. 


° wm withdraw window 


Arranges for window to be withdrawn from the screen. 


26.2 Window Sizes 


Even if a Tk application never invokes the wm command, Tk still 
communicates with the window manager on the application’s behalf so that 
its toplevel windows appear on the screen. By default each toplevel 
window appears in its natural size, which is the size it requested using the 
normal Tk mechanisms for geometry management. Tk forwards the natural 
size to the window manager, and most window managers honor the request. 
If the natural size of a toplevel window should change, Tk forwards the new 
size to the window manager, and the window manager resizes the window 
to correspond to the latest request. 

If the user interactively resizes a toplevel window, the window’s natural 
size is ignored from that point on. Regardless of how the internal needs of 
the window change, its size remains as set by the user. A similar effect 
occurs if you invoke the wm geometry command, as in the following example: 


wm geometry .w 300x200 
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This command forces .w to be 300 pixels wide and 200 pixels high, just as if 
the user had resized the window interactively. The natural size for .w is 
ignored, and the size specified in the wm geometry command overrides any size 
that the user might have specified interactively (though the user can resize 
the window again to override the size in the wm geometry command). 

If you would like to restore a window to its natural size, you can invoke wm 
geometry With an empty geometry string: 


wm geometry .w {} 


This causes Tk to forget any size specified by the user or by wm geometry, $O 
the window returns to its natural size. 

If you want to limit interactive resizing, you can invoke wm minsize and/or wm 
maxsize to specify a range of acceptable sizes. For example, the script 


wm minsize .w 100 50 
wm maxsize .w 400 150 


allows .w to be resized but constrains it to be 100 to 400 pixels wide and 50 
to 150 pixels high. If the command 


wm minsize .w 1 1 


is invoked, there is effectively no lower limit on the size of .w. If you set a 
minimum size without a maximum size, the maximum size is the size of the 
display; if you set a maximum size without a minimum size, the minimum 
size 1S unconstrained. You can disable or enable interactive resizing with 
the wn resizable command, which allows you to set two Boolean values to 
indicate whether horizontal or vertical resizing is allowed. The following 
command disables both horizontal and vertical resizing, fixing the window 
at whatever size it is when the command is executed: 


wm resizable .w 00 


In addition to constraining the dimensions of a window, you can also 
constrain its aspect ratio (width divided by height) using the wm aspect 
command. For example, 


wm aspect .w1341 


tells the window manager not to let the user resize the window to an aspect 
ratio less than 1/3 or greater than 4. See Figure 26.1 for examples of various 
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aspect ratios. After the command just given, the window manager allows the 
user to resize .w to any of the shapes between the two dotted lines but not to 
those outside the dotted lines. 


Figure 26.1 The aspect ratio of a window is its width divided by its height. 


<1/3 Aspect ratio increasing ——> > 4/1 


26.3 Window Positions 


Controlling the position of a toplevel window is simpler than controlling its 
size. Users can move windows interactively, and an application can also 
move its own windows using the um geometry command. For example, the 
command 


wm geometry .w +100+200 


positions .w so that its upper left corner is at pixel (100,200) on the display. 
If either of the + characters is replaced with a -, the coordinates are 
measured from the right and bottom sides of the display. For example, 


wm geometry .w -0-0 


positions .w at the lower right corner of the display. 


Note 


If you are using a virtual root window manager, the positions you 
specify iN a wm geometry command may be relative either to the screen or 
to the virtual root window. Consult the documentation for your window 
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manager to see which of these is the case. With some window 
managers, you can use options to the window manager along with the wm 
positionfrom Command to control which interpretation is used. 


26.4 Gridded Windows 


In some cases it doesn’t make sense to resize a window to arbitrary pixel 
sizes. For example, consider the application shown in Figure 26.2. When 
the user resizes the toplevel window, the text widget changes size in 
response. Ideally the text widget should always contain an integral number 
of characters in each dimension, and sizes that result in partial characters 
should be rounded off. 


Figure 26.2 An example of gridded geometry management 


_@ © @ Declaration of indepen... 


When in the Course of human 
events, it becomes necessary a 

@ © @ Declaration of independence for one people to dissolve 

| the political bands which 

have connected them with 

another, and to assume among 

the powers of the earth, the 

separate and equal atation to 

which the Laws of Nature and 

of Nature's God entitle them, 

5 decent respect to the 

opinions of mankind requires 

that they should declare the 

causes which impel them to 

the separation. 


When in the Course of human events, it 
becomes necessary for one people to 0 
dissolve the political banda which have 
connected them with another, and to 

assume among the powers of the earth, 

the separate and equal station to which 

the Laws of Nature and of Nature's God 
entitie them, a decent respect to the 
Opinions of mankind requires that they 
should Geciare the causes which impel 

them to the separation. 4 


We hold these truths to be 


self-evident, that all men ng 
are crested equal, that they . 
| 

(a) (b) 


Gridded geometry management accomplishes this effect. When gridding is 
enabled for a toplevel window, the window’s dimensions are constrained to 
lie on an imaginary grid. The geometry of the grid is determined by one of 
the widgets contained in the toplevel window (e.g., the text widget in Figure 
26.2) so that the widget always holds an integral number of its internal 
objects. Usually the widget that controls the gridding is a text-oriented 
widget such as an entry or listbox or text. If the user interactively resizes the 
window from the dimensions in Figure 26.2(a) to those in Figure 26.2(b), 
the window manager rounds off the dimensions so that the text widget holds 
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an integral number of characters in each dimension. 

To enable a widget to control the grid for a toplevel window, set the -setgria 
option to : in the controlling widget. Only one widget can control the 
gridding for a given toplevel. The following code was used in the example 
in Figure 26.2, where the text widget is .«: 


.t configure -setgrid 1 


This command has several effects. First, it identifies to the toplevel window 
that this widget determines the grid size for the overall window. Second, it 
changes the unit of measurement for dimensions used in the wm geometry 
command. For the text widget, the unit of measurement is a character. For 
example, the command 


wm geometry . 50x30 


sets the size of the main window so that .< is 50 characters wide and 30 
lines high. The units 1n wm minsize and wm maxsize aS Well as the -wiatn and - 
neight Options for the widget itself are also measured in grid units instead of 
points. 

Gridding may also be defined using the wm gria command. This is used when 
the grid unit size is determined by something other than a widget. 


Note 


Gridding works well only for windows with fixed-size objects, such 
as a text window with a monospace font. If different characters have 
different sizes, the window’s size won’t necessarily be an integral 
number of characters. 

Furthermore, in order for gridding to work correctly, you must have 
configured the internal geometry management of the application so that 
the controlling window stretches and shrinks in response to changes in 
the size of the toplevel window, for example, by gridding it with the 
option -sticky nsew. 


26.5 Window States 
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At any given time each toplevel window is ina given state. In the normal or 
deiconified state the window appears on the screen. In the zoomed state, 
supported on Windows and Mac OS X systems, the window appears in a 
maximized state on the screen. In the iconified state the window does not 
appear on the screen, but an icon is displayed in the taskbar or desktop 
instead. In the withdrawn state the window does not appear anywhere on the 
screen and the window is ignored completely by the window manager. 

New toplevel windows start off in the normal state. You can use the 
facilities of your window manager to iconify a window interactively, or you 
can invoke the wm iconigy command within the window’s application; for 
example: 


wm iconify .w 


If you invoke wm iconity immediately, before the window first appears on the 
screen, it starts off in the iconic state. The command wm daeiconity CAUSES a 
window to revert to normal state again. 

The command wm witharaw places a window in the withdrawn state. If invoked 
immediately, before a window has appeared on the screen, the window 
starts off withdrawn. The most common use for this command is to prevent 
the main window of an application from ever appearing on the screen (in 
some applications the main window serves no purpose and the user 
interface is presented with a collection of toplevel windows). Once a 
window has been withdrawn, it can be returned to the screen with either wm 
deiconify OF wm iconify. 


The wm state Command sets or returns the current state for a window: 


wm iconify .w 
wm state .w 
=> iconic 


26.6 Decorations 


When a window appears on the screen in the normal state, the window 
manager usually adds a decorative frame around it. The frame typically 
displays a title for the window and contains interactive controls for resizing 
the window, moving it, and so on. For example, Mac OS X Aqua decorated 
the window in Figure 26.2. 

The wm titre command allows you to set the title that is displayed in a 
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window’s decorative frame. For example, the command 


wm title . "Declaration of Independence" 


was used to set the title for the window in Figure 26.2. 

Other wa commands have indirect effects on the interactive frame controls. 
For example, if the resizable flags are set to false (wm resizable . 0 0), the 
maximize button or the resize grab handle (lower right corner) is not 
displayed. The exact change of the controls depends on which window 
manager 1s in use. 

The wm command provides several options for controlling what is displayed 
when a window is iconified. First, you can use wm iconname to specify a title 
to display in the icon. Second, some window managers allow you to specify 
an image to be displayed in the icon. The wm iconpnoto command allows you 
to set this image. Some older window managers support only simple two- 
color bitmaps for icons. The wm iconbitmap and wm iconmask are used to set a 
two-color icon and transparency mask respectively. Third, some window 
managers allow you to use one window as the icon for another; wn iconwindow 
sets up such an arrangement if your window manager supports it. Finally, 
you can specify a position on the screen for the icon with the wm iconposition 
command. 


Note 


Almost all window managers support wm iconname. The wm iconphoto 
command is handled differently on different window managers, fewer 
Support um iconbitmap, and almost no window managers support wm 
iconwindow very well. You need to experiment with these commands to 
determine which ones meet your requirements based on the platform or 
platforms your application needs to support. 


26.7 Special Handling: Transients, Groups, and 
Override-Redirect 


You can ask the window manager to provide special treatment for windows 
to implement features such as toolbars, nonmodal dialog boxes, and splash 
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screens. 
You can mark a toplevel window as transient with a command like the 
following: 


wm transient .w . 


This indicates to the window manager that .w is a short-lived window such 
as a dialog box, working on behalf of the application’s main window. The 
last argument to wm transient (which is . in the example) is referred to as the 
master for the transient window. Most window managers ensure that a 
transient window always remains above its master. Additionally, the 
window manager may treat transient windows differently from other 
windows by providing less decoration or by iconifying and deiconifying 
them whenever their master is iconified or deiconified. 

In situations where several long-lived windows work together, you can use 
the wm group command to tell the window manager about the group. The 
following script tells the window manager that the windows .top1, .top2, 
.top3, and .topa are working together as a group, and .top: is the group 
leader: 


foreach i {.top2 .top3 .top4} { 
wm group $i .topl 
} 


The window manager can then treat the group as a unit, and it may give 
special treatment to the leader. For example, when the group leader is 
iconified, all the other windows in the group might be removed from the 
display without icons being displayed for them: the leader’s icon represents 
the whole group in this case. When the leader’s icon is deiconified again, 
all the windows in the group might return to the display. The exact treatment 
of groups is up to the window manager, and different window managers may 
handle them differently. The leader for a group need not actually appear on 
the screen (e.g., it could be withdrawn). 

In some rare cases it is important for a toplevel window to be completely 
ignored by the window manager: no decorations, no_ interactive 
manipulation of the window via the window manager, no iconifying, and so 
on. Typical examples of such a window are a hover-help window or a 
splash screen. In these cases, the windows should be marked as override- 
redirect using a command similar to the following: 


wm overrideredirect .splash true 
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This command must be invoked before the window has actually appeared on 
the screen. 


Note 


Menus automatically mark themselves as override-redirect so you 
don’t need to do this for them. 


26.8 System-Specific Window Attributes 


Each windowing system has unique features that do not have any portable 
equivalent in other windowing systems. The wm attribute command ts used to 
query and set some of these unique features: 


wm attribute window ?attribute? ?value attribute value ...? 


Currently, all windowing systems support the following attributes: 
° -fullscreen boolean 
When true, the window fills the entire screen without any window manager 
decoration. This feature is usually used in conjunction with -topmost. 
© -topmost boolean 
When true, the window always appears above all others. 
On Windows, the following additional attributes are available: 
® -alpha number 
Controls the transparency of the toplevel. Valid values are in the range 0.0 
(transparent) to 1.0 (opaque). 
® -disabled boolean 
When true, the window is ina disabled state and cannot take focus. 
® -toolwindow boolean 
When true, causes the window to take on the style of a tool window. 
® -transparentcolor color 
Specifies the transparent color of the toplevel. If the empty string is 
specified (default), no transparent color is used. 
On Mac OS X Aqua, the following additional attributes are available: 


® -alpha number 


Controls the transparency of the toplevel. Valid values are in the range 0.0 
(transparent) to 1.0 (opaque). 
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© -modified boolean 


When true, the window close icon shows the modified state. This is 
typically used to show that the application has modified, unsaved data. 

® -notify boolean 
When true, it causes the icon in the dockbar to bounce and, if enabled, the 
voice announcement is triggered to indicate that the application needs 
attention. 

© -titlepath pathname 
When set, specifies the path of the file referenced by the icon in the title bar 
of the window, which can be dragged and dropped in lieu of the file’s 
Finder icon. 
On X11, the following additional attributes are available: 


© -zoomed boolean 


When true, maximizes the window as with wm state Of zoomea for Windows 
and Mac OS X. 


26.9 Dockable Windows 


The wm manage Command is used to make any window into a toplevel window 
managed by the window manager, and the wn forgee command performs the 
inverse operation, informing the window manager to stop managing the 
window. Although this command can work with any widget, it is ideally 
suited for use with the toplevel and frame widgets. These commands are 
used to effect a “dock” operation, where two toplevel windows are joined 
to make a single toplevel window, and an “undock” operation, where a 
subwindow is removed from a toplevel window and made into a separate 
toplevel window. These commands alone do not perform the complete 
operation but when combined with another geometry manager command 
complete the task. A typical dock operation would be 


wm forget .top. frame 1 
grid.top.frame1 -row 0 -column | 


An undock operation would be 


grid forget .top.frame1 
wm manage .top.frame1 


There are some limitations to be aware of when using the wn manage 
command: 
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¢ When “docking,” the widget must be a child of the geometry 
manager’s master widget. 

¢ Toplevel class windows behave like frames when not managed by the 
window manager, so only the frame properties of the widget apply. 
This means the -menu setting is ignored and the menu bar is no longer 
available in the window. It does reappear when the toplevel 
window is again managed by the window manager. 

¢ Only a toplevel widget can have a menu bar because this is the only 
Tk widget with a -menu option. 

¢ Bindtags that have been set explicitly in any subwindow of a docked 
or undocked window must be reset or updated. This is because the 
bindtag contains the widget path of the toplevel window. Since the 
path of the toplevel window has been changed as a result of the 
operation, the old bindtag is no longer appropriate. (See Section 
22.8 for more information on bindtags.) 


26.10 Window Close 


Closing a toplevel window can be performed by the Tcl script using the 
destroy Command, or by the window manager when the user presses the close 
button on the decoration frame. There are times when it is necessary for the 
application to be notified when the window manager closes a window so 
that additional actions may be taken or the operation prevented altogether. 
This operation can be intercepted with the wm protoco1 command. There are 
several window manager protocols that are implemented in X11, but the 
only one relevant here and uniformly recognized on all platforms and 
window managers is the wv peters winnow protocol. The window manager 
invokes this protocol when it wants the application to destroy the window, 
as when the user asks the window manager to close the window. 

The wm protocol command arranges to execute a script whenever a particular 
protocol is triggered. For example, the command 


wm protocol . WM DELETE WINDOW { 


set response [tk_messageBox -type yesno \ 
-message "Really quit?"] 
if {Sresponse eq "yes"} { 
Gestroy . 
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prompts the user for confirmation to quit whenever the window manager 
asks the application to close its main window. If the user selects “No,” the 
window is not actually destroyed. If you've not used the wm protocoi 
command to register a handler for the wa pzteTe_wrypow protocol on a toplevel, 
Tk takes the default action of destroying the window. For other protocols, 
nothing happens unless you specify an explicit handler. 


26.11 Session Management 


Some window managers manage the user’s session, recording which 
applications are running when the session is closed (1.e., when the user logs 
off the system) and starting those same applications when a new session is 
started (1.e., when the user logs on to the system). Two special wm commands 
can provide the necessary information so that the window manager can 
successfully save and restore the Tk application. The wm ciient command 
provides the name of the host machine running the application. The wm commana 
command provides a program path name with arguments (i1.e., a full 
command line) that the session manager can use to restart the application. 
For example, 


wm client . sprite.berkeley.edu 
wm command . {browse /usr/local/bin} 


indicates that the application is running on the machine sprite.berkeley.edu and 
was invoked with the shell command browse/usr/1ocal/bin. 
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27. Focus, Modal Interaction, and Custom 
Dialogs 


This chapter discusses the management of the input focus window and 
modal windows. Input focus determines which widget in your application 
receives keyboard events. A modal window 1s a child window that requires 
users to interact with it before they can continue interacting with the main 
window. The most common examples of modal windows are dialogs such 
as a file selector. 

The default Tk bindings automatically handle focus management and modal 
interactions in a way that most users expect. For example, clicking on an 
entry automatically gives it focus so that the user can enter text into it, and 
the dialogs provided by Tk automatically behave as modal windows. 
Typically the only situation where you would manage focus and modal 
interaction explicitly 1s if you need to create you own custom dialogs for 
your application. 


27.1 Commands Presented in This Chapter 


This chapter describes the following commands for use in manipulating 
focus, modal interaction, and custom dialogs: 

* focus 
Returns the path name of the focus window on the display containing the 
application’s main window, or an empty string if no window in this 
application has the focus on that display. 

® focus -displayof window 
Returns the name of the focus window on the display containing wincow. If the 
focus window for window's display isn’t in this application, the return value is 
an empty string. 

° focus -lastfor window 
Returns the name of the most recent window to have the input focus among 
all the windows in the same toplevel as window. Ifno window in that toplevel 
has ever had the input focus, or if the most recent focus window has been 
deleted, the name of the toplevel is returned. 


® focus ?-force? window 
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Sets the application’s focus window to window. The -force option also forces 
the application to have focus; this feature should be used sparingly. 

® tk_focusFollowsMouse 
Switches Tk to an implicit focus model, where focus is set to a window 
whenever the mouse enters it. 

® tk_focusNext window 
Returns the next window after window in the focus order. 

® tk_focusPrevious window 
Returns the window Just before window in the focus order. 

® grab ?-global? window 
Same as the grab set command. 

® grab current ?window? 
Returns the name of the current grab window for window's display, or an 
empty string if there is no grab for that display. If window is omitted, it returns 
a list of all windows grabbed by this application for all displays. 

® grab release window 
Releases the grab on winaow, if there is one. 

© grab set ?-global? window 
Sets a grab on window, releasing any previous grab on windows display. If - 
global 18 specified, the grab is global; otherwise it is local. 

® grab status window 
Returns none if no grab 1s currently set on window, 10ca1 1f a local grab is set, 
and giobai 1fa global grab is set. 

® tkwait variable varName 
Waits until the variable varvame changes value, then returns. 

* tkwait visibility window 


Waits until the visibility state of winaow changes, then returns. 


® tkwait window window 


Waits until window is destroyed, then returns. 


27.2 Input Focus 


At any given time one window of an application is designated as the input 
focus window, or focus window for short. All keystrokes received by the 
application are directed to the focus window and are processed according 
to its event bindings; if the focus window has no bindings for the keystroke, 
the keystroke is ignored. 
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Note 


The focus window is used only for key press and key release events. 
Mouse-related events, such as enter, leave, button press, and button 
release, are always delivered to the window under the mouse, 
regardless of the focus window. Furthermore, the focus window 
determines only what happens once a keystroke event arrives at a 
particular application; it does not determine which of the applications 
on the display receives keystrokes. The choice of a focus application is 
made by the window manager, not Tk. 


27.2.1 Focus Model: Explicit versus Implicit 


There are two possible ways of handling the input focus, known as the 
implicit and explicit focus models. In the implicit model the focus follows 
the mouse: keystrokes are directed to the window under the mouse pointer, 
and the focus window changes implicitly when the mouse moves from one 
window to another. In the explicit model the focus window is set explicitly 
and doesn’t change until it is explicitly reset; mouse motions do not 
automatically change the focus. 

Tk implements the explicit focus model, for several reasons. First, the 
explicit model allows you to move the mouse cursor out of the way when 
you’re typing in a window; with the implicit model you’d have to keep the 
mouse in the window while you type. Second, and more important, the 
explicit model allows an application to change the focus window without 
the user moving the mouse. For example, when an application pops up a 
dialog box that requires type-in, such as one that prompts for a file name, it 
can set the input focus to the appropriate window in the dialog without your 
having to move the mouse, and it can move the focus back to its original 
window when you're finished with the dialog box. This allows you to keep 
your hands on the keyboard. Similarly, when you’re typing in a form, the 
application can move the input focus to the next entry in the form each time 
you press the Tab key, so that you can keep your hands on the keyboard and 
work more efficiently. Last, 1f you want an implicit focus model, it can 
always be achieved with event bindings that change the focus each time the 
mouse cursor enters a new window. Tk provides a command named 
tk _focusFollowsMouse that switches your application to an implicit focus model: 
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it reconfigures Tk bindings so that the focus is set to a window whenever 
the mouse enters it. 

Tk applications don’t need to worry about the input focus very often 
because the default bindings for text-oriented widgets already take care of 
the most common situations. For example, when you click mouse button 1 
over an entry or text widget, the widget automatically makes itself the focus 
window. As an application designer you need to set the focus only in cases 
like those in the previous paragraph where you want to move the focus 
among the windows of your application to reflect the flow of work. You 
should be careful when doing this, though, because most windowing systems 
use the explicit focus model. Changing the model can prove disconcerting to 
your users. 


27.2.2 Setting the Input Focus 


To set the input focus, invoke the focus command with a widget name as 
argument: 


focus .dialog.entry 


This directs subsequent keystrokes received by the application to 
.dialog.entry; the previous focus window no longer receives keystrokes. The 
new focus window displays some sort of highlight, such as a blinking 
insertion cursor, to indicate that it has the focus, and the previous focus 
window stops displaying its highlight. 


Note 


The focus -force option also attempts to force the application to have 
focus; not all window managers honor this request. In general, forcing 
focus to your application should be used sparingly; it is akin to going 
up to a person at a party and shouting, “Pay attention to me!” 


27.2.3 Querying the Input Focus 


Sometimes it’s useful to query the current focus window, particularly if your 
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application needs to redirect focus temporarily to a different window. The 
focus Command returns the name of the application’s current focus window, 
or an empty string if no window in the application is currently the focus 
window. In contrast, focus -1astfor returns the name of the last focus window 
within the toplevel containing the specified window; this 1s the name of the 
window that receives the input focus the next time the window manager 
gives focus to the toplevel. 


27.3 Modal Interactions 


Usually the user of a Tk application has complete control over what 
operations to perform and in what order. The application offers a variety of 
panels and controls, and the user selects among them. However, there are 
times when it’s useful to restrict the user’s range of choices or force the user 
to do things in a certain order; these are called modal interactions. The best 
example of a modal interaction is a dialog box: the application is carrying 
out some function requested by the user such as writing information to a file 
when it discovers that it needs additional input from the user, such as the 
name of the file to write. It displays a dialog box and forces the user to 
respond to the dialog box, for example, by selecting a file name, before 
proceeding. After the user responds, the application completes the operation 
and returns to its normal mode of operation where the user can do anything 
he or she pleases. 

Tk provides two mechanisms for use in modal interactions. First, the grap 
command allows you to restrict the user temporarily so that he or she can 
interact with only a few of the application’s windows (for example, only the 
dialog box). Second, the txwait command allows you to suspend the 
evaluation of a script until a particular event has occurred, such as the user 
responding to a dialog box, and then continue the script after this has 
happened. 


Note 


A word of caution is in order here. Although modal interactions are 
sometimes useful, most experts agree that they should be kept to a 
minimum. Users can become frustrated if their range of choices is 
constantly being limited by modes, and mode switches can be 
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confusing. 


27.3.1 Grabs 


Mouse events such as button presses and mouse motions are normally 
delivered to the window under the pointer. However, it is possible for a 
window to claim ownership of the mouse so that mouse events are 
delivered only to that window and its descendants in the Tk window 
hierarchy. This is called a grab. When the mouse is over one of the 
windows in the grab subtree, mouse events are delivered and processed just 
as if no grab were in effect. When the mouse is outside the grab subtree, 
button presses and releases and mouse motion events are delivered to the 
grab window instead of the window under the mouse, and window entry and 
exit events are discarded. Thus, a grab prevents the user from interacting 
with windows outside the grab subtree. 

The crab command sets and releases grabs. For example, if you’ve created a 
dialog box named .aig and you want to prevent the user from interacting with 
any window except .aig and its subwindows, you can invoke the command 


grab set .dlg 


After the user has responded to the dialog box, you can release the grab with 
the command 


grab release .dlg 


If the dialog box is destroyed after the user has responded to it, there’s no 
need to invoke grab release: Tk releases the grab automatically when the grab 
window is destroyed. 

To see how grabs work, try the following script: 


button .bl -text "Unclickable 1" 
button .b2 -text "Unclickable 2" 


button .b3 -text "Grabby Button" -command { destroy .b3 } 
label .1 -text "Text entry" 
entry .e 


pack .bl ;b2 .b3 <1 <e 
grab .b3 


In this script, you can interact with only one widget, the button .»3, which 
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has a grab on input events. You cannot set the keyboard focus to the entry 
box or enter text. If you click on .»3, labeled ““Grabby Button,” the callback 
script destroys the button. This finally allows you to interact with the other 
buttons as well as the entry widget. 

The most common way to use grabs is to set a grab ona toplevel window so 
that only a single panel or dialog box is active during the grab. However, it 
is possible for the grab subtree to contain additional toplevel windows; 
when this happens, all of the panels or dialogs corresponding to those 
toplevel windows are active during the grab. 


Note 


Some window managers cause grab to fail or to raise an error if you try 
to set a grab on a window that is not visible. Section 27.3.4 describes 
how to use the txwait visibility command to wait for a window to 
become visible. 


27.3.2 Local versus Global Grabs 


Tk provides two forms of grab, local and global. A /ocal grab affects only 
the grabbing application: if the user moves the pointer into some other 
application on the display, he or she can interact with the other application 
as usual. You should always try to use local grabs, and they are the default 
in the grab set command. A global grab takes over the entire display so that 
you cannot interact with any application except the one that set the grab. To 
request a global grab, specify the -gioba1 switch to grab set as in the 
following command: 


grab set -global .dlg 


Global grabs are rarely needed, and they are tricky to use (if you forget to 
release the grab, your display locks up so that it is unusable). One place 
where global grabs are used internally by Tk is for pull-down menus. 


Note 
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If you need to implement a global grab in your application, it can be 
useful to install some sort of back door to regain control or let you kill 
the application if you accidentally lock your display. For example, you 
could install a key binding on the ai: bindtag, or set an after event 
handler to exit your application after some time. 


27.3.3 Keyboard Handling during Grabs 


Local grabs have no effect on the way the keyboard is handled: keystrokes 
received anywhere in the application are forwarded to the focus window as 
usual. Most likely you should set the focus to a window in the grab subtree 
when you set the grab. Windows outside the grab subtree can’t receive any 
mouse events, so they are unlikely to claim the focus away from the grab 
subtree. Thus, the grab is likely to have the effect of restricting the keyboard 
focus to the grab subtree; however, you are free to move the focus anywhere 
you wish. If you move the pointer into another application, the focus moves 
to that other application just as if there had been no grab. 

During global grabs Tk also sets a grab on the keyboard so that keyboard 
events go to the grabbing application even if the pointer is over some other 
application. This means that you cannot use the keyboard to interact with 
any other application. Once keyboard events arrive at the grabbing 
application, they are forwarded to the focus window in the usual fashion. 


27.3.4 Waiting: The txwait Command 


The second aspect of a modal interaction is waiting. Typically you want to 
suspend a script during a modal interaction and resume it when the 
interaction is complete. For example, if you display a file selection dialog 
during a file write operation, you probably want to wait for the user to 
respond to the dialog, then complete the file write using the name supplied 
in the dialog interaction. Or when you start up an application, you might 
wish to display an introductory panel that describes the application and 
keep this panel visible while the application initializes itself; before going 
off to do the main initialization, you'll want to be sure that the panel is 
visible on the screen. The txwait command can be used to wait in situations 
like these. 

tkwait has three forms, each of which waits for a different event to occur. 
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The first form waits for a window to be destroyed, as in the following 
command: 


tkwait window .dlg 


This command does not return until .aig has been destroyed. You might 
invoke this command after creating a dialog box and setting a grab on it; the 
command doesn’t return until after the user has interacted with the dialog in 
a way that causes it to be destroyed. While txwait 1s waiting, the application 
responds to events so the user can interact with the application’s windows. 
In the dialog box example, bindings must exist to destroy the dialog once the 
user’s response is complete (e.g., the user clicks on the OK button). The 
bindings for the dialog box might also save additional information in 
variables (such as the name of a file or an identifier for the button that was 
pressed). This information can be used once txwait returns. 

The following script creates a panel with two buttons labeled “OK” and 
“Cancel,” waits for the user to click on one of the buttons, and then deletes 
the panel: 


toplevel .panel 

button .panel.ok -text OK -command { 
set label OK 
destroy .panel 


} 
J 


button .panel.cancel -text Cancel -command { 
set label Cancel 
destroy .panel 

} 

pack .panel.ok -side left 

pack .panel.cancel -side right 

grab set .panel 

tkwait window .panel 

puts "You clicked Slabel" 


When the exwait Command returns, the variable iape1 contains the label of the 
button on which you clicked. 

The second form for txwait waits for the visibility state of a window to 
change. For example, the command 


tkwait visibility .intro 


does not return until the visibility state of .intro has changed. Typically this 
command is invoked just after a new window is created, in which case it 
doesn’t return until the window becomes visible on the screen. txwait 
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visibility can be used to wait for a window to become visible before setting 
a grab on it, or to make sure that an introductory panel is on the screen 
before invoking a lengthy initialization script. Like all forms of txwait, tkwait 
visibility responds to events while waiting. 

The third form of txwait 1s equivalent to the vwait command. In this form, the 
command doesn’t return until a given variable has been modified. For 
example, the command 


tkwait variable x 


does not return until variable x has been modified. This form of txwait is 
typically used in conjunction with event bindings that modify the variable. 
For example, the following procedure uses txwait variabie to implement 
something analogous to txwait window, except that you can specify more than 
one window and the procedure will return as soon as any of the named 
windows has been deleted (it returns the name of the window that was 
deleted): 


proc waitWindows args { 
global dead 


foreach w Sargs { 


tkwait variable dead 
return Sdead 


t 
bind Sw <Destroy> "set dead Sw" 


27.4 Custom Dialogs 


Tk includes a number of built-in dialogs, such as tx getopenriie, that you 
should use if they meet your needs. See Section 18.14 for a description of 
the built-in dialogs provided by Tk. If none of these is suitable, you can 
create a custom dialog. Your custom dialog should be a toplevel window. 
You should also register your toplevel window as a transient for your 
application’s main window using a command like the following, as 
described in Chapter 26: 


wm transient .dialog . 


This command registers the toplevel window .aiaicg as a transient window 
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on behalf of the main window ., so that the window manager can choose to 
provide dialog-specific decorations for your dialog window. 


Note 


Some window managers create the window as withdrawn if the parent 
window is withdrawn or iconified. Combined with the grab that you 
put on the dialog window, this can hang the entire application. 
Therefore, the safest approach is to make the dialog transient only if 
the parent is viewable. You could accomplish this with the winro 
viewable command as follows: 


if {[winfo viewable .]} { 
wm transient .dialog . 
} 


When you have a lot of widgets for your dialog, you can hide the window 
until all the widgets are ready. In window manager terms, you withdraw the 
window and then later deiconify it (all these terms come from the X 
Window System); for example: 


toplevel .dialog 
wm withdraw .dialog 


# Create and manage all the widgets... 
wm Geiconify .dialog 


You should also set the title and a script to handle the close button (as 
described in Chapter 26); for example: 


wm title .dialog "Create User Account" 
wm protocol .dialog WM_DELETE WINDOW "cancelDialog" 


This example calls the procedure canceipialog When the user clicks on the 
close button for the window. If your dialog has a “Cancel” button, it’s often 
a good idea to use the same script as for that button. In fact, you can simply 
invoke the “Cancel” button’s script in this case, for example: 


wm protocol .dialog WM DELETE WINDOW { 
.dialog.cancel invoke 
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For data-entry widgets, you normally use a grid-based layout to manage the 
widget positions. Using a grid allows the prompts and data-entry widgets to 
line up. And if you want the dialog to be modal, follow the techniques 
described in this chapter; for example: 


wm Geiconify .dialog 
tkwait visibility .dialog 
grab set .dialog 

tkwait window .dialog 


These commands wait until the dialog window is destroyed. 


Note 


On some window managers, it is possible that these txwait OF grab set 
commands will raise an error condition. Therefore, it’s safest to run 
each of these using a catch command to silently ignore these errors. 


The following script pulls all these pieces together to create a simple main 
window and a modal dialog. In this case, the dialog gathers input to set up a 
user account for some hypothetical Internet site. To keep the example 
simple, the main window sports two buttons, one to display the “Create 
Account” dialog and one to exit the application. The script follows: 
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# Tk custom dialog example 


proc cancelDialog {} { 
destroy .dialog 
} 


proc createAccount {} { 
global username password firstname lastname 
puts "Create account for $firstname $lastname." 
puts “With user name: Susername password S$password." 


destroy .dialog 


} 


proc showCreateAccount {} { 
global username password firstname lastname 
set firstname "" 
set lastname "" 
set username "" 
set password "" 


toplevel .dialog 
wm withdraw .dialog 


ttk::frame .dialog.f -relief flat 


# Login 

ttk::labelframe .dialog.f.login -text "Login:" 

ttk::label .dialog.f.login.userl -text "User Name:" 

ttk:;:entry .dialog.f,login.usert -textvariable username 

ttk::label .dialog.f.login.passl -text "Password:" 

ttk::entry .dialog.f.login.passt -show "*" \ 
-textvariable password 
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grid config .dialog.f.login.userl \ 
-column 0 -row 0 -sticky e 
grid config .dialog.f.login.passl \ 
-column 0 -row 1 -sticky e 
grid config .dialog.f.login.usert \ 
-column 1 -row 0 -sticky snew 
grid config .dialog.f.login.passt \ 
-column 1 -row 1 -sticky snew 


pack .dialog.f.login -padx 5 -pady 10 


# User information 
ttk::labelframe .dialog.f.userinfo \ 

-text "User Information:" 
ttk::label .dialog.f.userinfo.firstl -text "First Name:" 
ttk::entry .dialog.f.userinfo.firstt \ 

-textvariable firstname 
ttk::label .dialog.f.userinfo.lastl -text "Last Name:" 
ttk::entry .dialog.f.userinfo.lastt \ 

-textvariable lastname 


grid config .dialog.f.userinfo.firstl \ 
-column 0 -row 0 -sticky e 

grid config .dialog.f.userinfo.lastl \ 
-column 0 -row 1 -sticky e 

grid config .dialog.f.userinfo.firstt \ 
-column 1 -row 0 -sticky snew 

grid config .dialog.f.userinfo.lastt \ 
-column 1 -row 1 -sticky snew 


pack .dialog.f.userinfo -padx 5 -pady 10 


# Action buttons 
ttk::frame .dialog.f.buttons -relief flat 


ttk::button .dialog.f.buttons.ok -text "Create Account" \ 
-command {createAccount } 

ttk::button .dialog.f.buttons.cancel -text "Cancel" \ 
-command {cancelDialog} 


pack .dialog.f.buttons.ok -side left 

pack .dialog.f.buttons.cancel -side right 
pack .dialog.f.buttons -padx 5 -pady 10 
pack .dialog.f 
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# Window manager settings for dialog 

wm title .dialog "Create User Account" 

wm protocol .dialog WM_DELETE WINDOW { 
.dialog.f.buttons.cancel invoke 

} 


wm transient .dialog 


# Ready to display the dialog 
wm Geiconify .dialog 


# Make this a modal dialog. 
catch {tk visibility .dialog} 
focus .dialog.f.login.usert 
catch {grab set .dialog} 
catch {tkwait window .dialog} 


ttk::button .createAccount -text "Create Account..." \ 
-command {showCreateAccount } 


ttk::button .exitButton -text "Exit" -command { exit } 


pack .createAccount .exitButton -padx 10 -pady 20 


In this script, the canceipialog procedure destroys the dialog window. The 
createAccount procedure acts as a placeholder for the actual code that would 
create a new user account. Figure 27.1 shows the main window. The 
showCreateAccount procedure creates and populates the create account dialog 
when the user clicks on the “Create Account” button. Figure 27.2 shows this 
dialog. While the “Create Account” dialog is visible, the main window 
does not accept keyboard or mouse input. The user then can enter in account 
information, including a password that is shown as asterisks. 


Figure 27.1 The main window 


Figure 27.2 The create account custom dialog 
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“HX Create User Account x} 


Login: 


UserNane:[bobmeiey 
pasonrdsee 


User Information: 


FestNane: Bob 
LastName: rey 


cats An 


Note 


An alternate approach would be to build the dialog once, and then use 
wm deiconify aNd wm withdraw to show and hide it as needed. This could 
save time if it were a particularly complex dialog. It also has the 
benefit of allowing widgets to maintain—and even update—their state 
while hidden, which could be quite useful for something like a 
preferences dialog. 
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28. More on Configuration Options 


Configuration options for widgets were introduced in previous chapters. 
You can specify configuration options when creating new widgets and 
modify them with the configure action for widget commands. This chapter 
describes two additional facilities related to options. The first part of the 
chapter describes the option database, which can be used to specify default 
values for options. The second part of the chapter describes the full syntax 
of the configure Widget command; it can be used to retrieve information about 
options as well as to modify options. 


28.1 Commands Presented in This Chapter 


This chapter discusses the following commands for manipulating 
configuration options. For a complete list of the options available for a 
particular widget class, see the reference documentation for the 
corresponding class command, such as wutton. 
° class widget ?0ptionName value optionName value ...? 
Creates a new widget with class ciass and path name wiaget and sets options 
for the new widget as given by optionname value pairs. Unspecified options are 
filled in using the option database or widget defaults. Returns wiager as the 
result. 
*° widget cget optionName 
Returns the value currently assigned to the option optionname for wiaget. 
° widget configure 
Returns a list whose elements are sublists describing all of the options for 
widget. Each sublist describes one option in the form described next. 
® widget configure optionName 
Returns a list describing the option optionname for wiaget. The list normally 
contains five values: optionname, the option’s name in the option database, its 
class, its default value, and its current value. If the option is a synonym for 
another option, the list contains two values: the option name and _ the 
database name for the synonym. 
° widget configure optionName value ?0ptionName value ...? 
Sets the value for each optionname Of wiaget to the corresponding vaiue. 


® option add pattern value ?priority? 
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Adds a new option to the option database as specified by pattern and vaiue. 
priority Must be either a number between 0 and 100 or a symbolic name (see 
the reference documentation for details on symbolic names); if omitted, it 
defaults to interactive (80). 
*® option clear 
Removes all entries from the option database. 
® option get widget dbName dbClass 
If the option database contains a pattern that matches widget, apame, and 
abciass, returns the value for the highest-priority matching pattern. Otherwise 
returns an empty string. 
® option readfile fileName ?priority? 
Reads ¢fiiewame, Which must have the standard format for a .xcefauits file, and 
adds all the options specified in that file to the option database at priority 


level priority. The priority defaults to interactive (so) 1f omitted. 


28.2 The Option Database 


The option database supplies values for configuration options that aren’t 
specified explicitly by the application designer. The option database is 
consulted when widgets are created: for each option not specified on the 
command line, the widget queries the option database and uses the value 
from the database, if there is one. If there is no value in the option database, 
the widget class supplies a default value. Values in the option database are 
usually provided by the user to personalize applications, for example, to 
specify consistently larger fonts. On Unix systems, Tk supports the 
RESOURCE MANAGER Property and .xdefauits file in the same way as other X 
toolkits. 

The option database shouldn’t be needed very often in Tk applications 
because widgets have reasonable default values for their options. If options 
do need to be changed, it is often easier to make the changes by invoking 
configure Widget commands from a Tcl script rather than creating entries in 
your .xdefauits file. The option database exists primarily to provide cultural 
compatibility with other X toolkits; you should use it as little as possible. 


28.3 Option Database Entries 


The option database contains any number of entries, where each entry 
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consists of two strings: a pattern and a value. The pattern specifies one or 
more widgets and options, and the value is a string to use for options that 
match the pattern. 

In its simplest form a pattern consists of an application name, an optional 
widget name, and an option name, all separated by dots. For example, here 
are two patterns in this form: 


wish.a.b.foreground 
wish.background 


The first pattern applies to the foregrouna option in the widget .a.» in the 
application wisn. In the second pattern the widget name is omitted, so the 
pattern applies to the main widget for wish. Each of these patterns applies to 
only a single option for a single widget. 

Patterns may also contain classes or wildcards, which allow them to match 
many different options or widgets. Any component of the widget name may 
be replaced by a class, in which case the pattern matches any widget that is 
an instance of that class. For example, the following pattern applies to all 
children of .2 that are checkbuttons: 


wish.a.Checkbutton. foreground 


Application and option names may also be replaced with classes. The 
application name is the name of the executable (which would be the 
interpreter name if you start an interactive interpreter, or the script name if 
you create a self-executing script); the application class is the application 
name with the initial letter capitalized. Individual options also have classes. 
For example, the class for the foreground Option 1S Foregrouna. Several other 
options such as insertBackgrouna (the color used for displaying an insertion 
cursor) also have the class roregrouna, $0 the following pattern applies to any 
of these options for any entry widget that is a child of .a in wisn: 


wish.a.Entry. Foreground 


Last, patterns may contain « wildcard characters. An « matches any number 
of window names or classes, as in the following examples: 


*Foreground 
*Button. foreground 


The first pattern applies to any option in any widget of any application as 
long as the option’s class is Foregrouna. The second pattern applies to the 
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foreground Option of any button widget in any application. The « wildcard may 
be used only for window or application names; it cannot be used for the 
option name (it wouldn’t make much sense to specify the same value for all 
options of a widget). 


Note 


This syntax for patterns is the same as that supported by the standard X 
resource database mechanisms in the X Window System. 


The database name for an option is usually the same as the name you would 
use in a widget creation command or a configure Widget command, except 
that there is no leading - and capital letters are used to mark internal word 
boundaries. For example, the database name for the -porderwiath option 1s 
porderwiath. The class for an option is usually the same as its database name 
except that the first letter 1s capitalized. For example, the class for the - 
porderwidth Option 1S Borderwiatn. It’s important to remember that in Tk classes 
always start with an initial capital letter; any name starting with an initial 
capital letter is assumed to be a class. 


28.4 The RESOURCE_MANAGER Property and xaerauits File 


When a Tk application starts up, Tk automatically initializes the option 
database. For an X windowing system, if there is a resource _manacer property 
on the root window for the display, the database is initialized from it. 
Otherwise, Tk checks the user’s home directory for a .xaefauits file and uses 
it if it exists. The initialization information has the same form whether it 
comes from the resource manacer property or the .xdefauits file. The syntax 
described here is the same as that supported by other X toolkits. 

Each line of initialization data specifies one entry in the resource database 
in a form such as the following: 


*Foreground: blue 


The line consists of a pattern («roregrouna 1n the example) followed by a 
colon, whitespace, and a value to associate with the pattern (1ue in the 
example). If the value is too long to fit on one line, it can be placed on 
multiple lines with each line but the last ending in a backslash-newline 
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sequence: 


*Gizmo.text: This is a very long initial \ 
\ 


value to use for the text option in all 


"Gizmo" widgets. 
The backslashes and newlines are not part of the value. 
Blank lines are ignored, as are lines whose first nonblank character is ¢ or :. 


28.5 Priorities in the Option Database 


It is possible for several patterns in the option database to match a 
particular option. When this happens, Tk uses a two-part priority scheme to 
determine which pattern applies. Tk’s mechanism for resolving conflicts is 
different from the standard mechanism supported by the X Toolkit (Xt). 

For the most part the priority of an option in the database is determined by 
the order in which it was entered into the database: newer options take 
priority over older ones. When specifying options (for example, by typing 
them into your .xdefauits file), you should specify the more general options 
first, and more specific overrides later. For example, if you want button 
widgets to have a background color of sisquei and all other widgets to have 
white backgrounds, put the following lines in your .xaefauits file: 


*background: white 
*Button. background: Bisque | 


The *backgrouna pattern matches any option that the *sutton.packgrouna pattern 
matches, but the «sutton.packgrouna pattern has higher priority since it was 
specified last. If the order of the patterns had been reversed, all widgets 
(including buttons) would have white backgrounds, and the «sutton.backgrouna 
pattern would have no effect. 

In some cases it may not be possible to specify general patterns before 
specific ones (for example, you might add a more general pattern to the 
option database after it has already been initialized with a number of 
specific patterns from the resource _manacer property). To accommodate these 
situations, each entry also has an integer priority level between 0 and 100, 
inclusive. An entry with a higher-priority level takes precedence over 
entries with lower-priority levels, regardless of the order in which they 
were inserted into the option database. Priority levels are not used very 
often in Tk; refer to the reference documentation for complete details on 
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how they work. 

Tk’s priority scheme is different from the scheme used by other X toolkits 
such as Xt. Xt gives higher priority to the most specific pattern; for example, 
.a.b. foreground 1S More specific than *foregrouna, SO it receives higher priority 
regardless of the order in which the patterns appear. In most cases this isn’t 
a problem: you can specify options for Xt applications using the Xt rules, 
and options for Tk applications using the Tk rules. In cases where you want 
to specify options that apply to both Tk applications and Xt applications, 
use the Xt rules but make sure that the patterns considered higher-priority by 
Xt appear later in your .xdefauits file. In general, you shouldn’t need to 
specify very many options to Tk applications (the defaults should always be 
reasonable), so the issue of pattern priority shouldn’t come up often. 


Note 


The option database is queried only for options not specified explicitly 
in the widget creation command. This means that the user cannot 
override any option that is specified in a widget creation command. If 
you want to specify a value for an option but allow the user to override 
that value through the resource_manacer property, you should specify the 
value for the option using the option command, described in the next 
section. 


28.6 The .ption. Command 


The option command allows you to manipulate the option database while an 
application is running. The command option aaa creates a new entry in the 
database and takes two or three arguments. The first two arguments are the 
pattern and value for the new entry, and the third argument, if specified, is a 
priority level for the new entry. The priority defaults to interactive (so) if 
omitted. For example, 


option add *Button. background Bisque 1 


adds an entry that sets the background color for all button widgets to sisquei. 
Changes to the option database affect only the application in which option aaa 
is invoked, and they apply only to new widgets created after option aaa 1S 
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executed; the database changes do not affect widgets that already exist. 

The option clear command removes all entries from the option database. On 
the next access to the database, it is re-initialized from the resource manacEeR 
property or the .xdefauits file. 

The command option reaafiie reads a file in the format described earlier for 
the resource_manacer property and make entries in the option database for each 
line. For example, the following command augments the option database 
with the information in the file newoptions: 


option readfile newOptions 


The option reaafile command can also be given a priority level as an extra 
argument after the file name to specify the priority at which the options are 
added. The priority defaults to interactive (so) 1f omitted. 

To query whether there is an entry in the option database that applies to a 
particular option, use the option get command: 


option get .a.b background Background 


This command takes three arguments: the path name of a widget (.a.»), the 
database name for an option (backgrouna), and the class for that option 
(Backgrouna). The command searches the option database to see if any entries 
match the given window, option, and class. If so, the value of the highest- 
priority matching option is returned. If no entry matches, an empty string is 
returned. 


28.7 The conticure Widget Command 


Every widget class supports a configure widget command. This command 
comes in three forms, which can be used both to change the values of 
options and to retrieve information about the widget’s options. 

Ifa configure Widget command is given two additional arguments, it changes 
the value of an option, as in the following example: 


.button configure -text Quit 


If the configure Widget command is given just one extra argument, it returns 
information about the named option: 


.button configure -text 
=> -text text Text { } Quit 
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The return value is normally a list with five elements. The first element of 
the list is the name of the option as you’d specify it on a Tcl command line 
when creating or configuring a widget. The second and third elements are a 
name and class to use for looking up the option in the option database. The 
fourth element is the default value provided by the widget class (a single 
space character in the preceding example), and the fifth element is the 
current value of the option. 

Some widget options are just synonyms for other options (e.g., the -»g option 
for buttons is the same as the -backgrouna option). Configuration information 
for a synonym is returned as a list with two elements consisting of the 
option’s command-line name and the option database name of its synonym: 


.button configure -bg 
=> -bg background 


If the configure Widget command is invoked with no additional arguments, it 
returns information about all of the widget’s options as a list of lists, where 
each element is a nested sublist of information for each option: 


-button configure 

= {-activebackground activeBackground Foreground 
systemButtonFacePressed systemBut tonPacePressed} 
{-activeforeground activeForeground Background 
systemPushButtonPressedText systemPushButtonPressedText} {-anchor 
anchor Anchor center center} {-background background Background 
White White) {-bd -borderwidth} {-ba -background} {-bitmap bitmap 
Bitmap {} {}} {-borderwidth borderWidth BorderWidth 2 2} {-command 
command Command {} {}} {-compound compound Compound none none} 
{-cursor cursor Cursor {} {}} {-default default Default disabled 
isabled} {-disabledforeground disabledForeground 
DisabledPoreground #ajaj3a3 #a3aj3a3)}) (-fo -foreground) {-font font 
Pont TkDefaultFont TkDefaultFont} {-foreground foreground 
Foreground systemButtonText systemButtonText) {-height height 
Height 0 0) {-highlightbackground highlightBackground 
HighlightBackground White White) {-highlightcolor highlightColor 
HighlightColor systemButtonFrame systemButtonFrame} 
{-highlightthickness highlightThichness HighlightThickness 4 4} 
{-image image Image {} {}} {-justify justify Justify center 
center} {-overrelief overRelief OverRelief {} {}} {-padx padX Pad 
i2 12} {-pady padY Pad 3 3} {-relief relief Relief flat flat} 
{-repeatdelay repeatDelay RepeatDelay 0 0} {-repeatinterval 
repeatInterval RepeatiInterval 0 0} {-state state State normal 
normal} {-takefocus takeFocus TakeFocus {} {}} {-text text Text {)} 
Quit} {-textvariable textVariable Variable {} {}} {-underline 
underline Underline -1 -1} {-width width Width 0 0) {f-wraplength 
wrapLength WrapLength 0 0} 
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28.8 The .cee Widget Command 


Every widget class supports a cget widget command. This command accepts 
the name of one option as an argument, and it returns the current value of that 
option. Pass the name of the option. For example: 


-button cget -text 


=> Quit 

-button cget -background 
=> White 

.button cget -padx 
=> 12 


.button configure -padx 150 
.button cget -padx 
=E50 


Unlike the configure widget command, which returns a list when used to 
retrieve widget values, the cget widget command returns just the value of the 
given option. 
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29. Odds and Ends 


This chapter describes several additional Tk commands: cestroy, which 
deletes widgets; upaate, which forces operations that are normally delayed, 
such as screen updates, to be done immediately; winso, which provides a 
variety of information about windows, such as their dimensions and 
children; »e11, for ringing the bell; and tx, which provides access to various 
internals of the Tk toolkit. This chapter also describes several predefined 
variables that are read or written by Tk and may be useful in Tk 
applications. 


29.1 Commands Presented in This Chapter 


This chapter discusses the following commands: 

© destroy window ?window window ...? 
Deletes each of the windows and all of the windows descended from them. 
The corresponding widget commands (and all widget states) are also 
deleted. 

® tk appname ?newName? 
Returns the current application name, or sets the application name to newname. 

® tk inactive ?-displayof window? ?reset? 
Returns the time in milliseconds since the last user interaction on the display 
containing window, which defaults to .. Including the eset argument resets the 
idle timer. 

® tk scaling ?-displayof window? ?number? 
Returns the scaling factor on the display containing window, which defaults to 
., or Sets it tO number. The scaling factor is a floating-point number expressing 
the number of pixels per typographic point. 

° tk windowingsystem 
Returns the current Tk windowing system, one of «11 (X11-based), winsz (MS 
Windows), Or aqua (Mac OS X Aqua). 

* update ?idletasks? 
Brings the display up to date and processes all pending events. If iaictasxs 1S 
specified, no events are processed except those in the idle task queue 
(delayed updates). 


® winfo option ?arg arg...? 


623 


Returns various pieces of information about windows, depending on the 
option argument. See the reference documentation for details. 


29.2 Destroying Widgets 


The destroy command deletes one or more widgets. It takes any number of 
widget names as arguments; for example: 


destroy .dlg1 .dlg2 


This command destroys .aigi and .aig2, including their widget state and the 
widget commands named after the windows. It also recursively destroys 
their children. The command «cestroy . destroys all of the widgets in the 
application; when this happens, most Tk applications exit. 


29.3 The upaaee Command 


Tk normally delays operations such as screen updates until the application 
is idle. For example, if you invoke a widget command to change the text ina 
button, the button doesn’t redisplay itself immediately. Instead, it schedules 
the redisplay to be done later and returns immediately. At some point the 
application becomes idle, which means that all existing events have been 
processed and the application is in the event loop and about to wait for 
another event to occur. At this point all of the delayed operations are carried 
out. Tk delays redisplays because it saves work when the same window is 
modified repeatedly: with delayed redisplay the window gets redrawn only 
once at the end. Tk also delays many other operations, such as geometry 
recalculations and window creation. 

For the most part the delays are invisible. Interactive applications rarely do 
very much work at a time, so Tk becomes idle again very quickly and 
updates the screen before the user can perceive any delay. However, there 
are times when the delays are inconvenient. For example, if a script is going 
to execute for a long time, you may wish to bring the screen up to date at 
certain times during its execution. The upaate command allows you to do this. 
If you invoke the command 


update idletasks 
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all of the delayed operations such as redisplays are carried out immediately; 
the command does not return until they have finished. 


Note 


Like the arter command, the upaate command used to be part of Tk. It 
has since moved to the Tcl core language, so you can use the upaate 
command in applications such as network servers that don’t need to 
present a graphical user interface. 


The following procedure uses upaate to flash a widget synchronously: 


proc flash {w option valuel value2 interval count} { 
for {set i 0} {$i < $count} {incr i} { 

Sw config Soption Svaluel 

update idletasks 

after S$interval 

Sw config Soption $value2 

update idletasks 

after Sinterval 


} 

This procedure flashes the widget a given number of times and doesn’t 
return until the flashing is complete. Tk never becomes idle during the 
execution of this procedure (the arter command doesn’t return to the event 
loop while it waits for the time to elapse), so the upaate commands are 
needed to force the widget to be redisplayed. Without the upaate commands 
no changes would appear on the screen until the script completed, at which 
point the widget’s option would change to vaiuez. 

If you invoke update Without the iaictasxs argument, all pending events are 
processed, too. You might do this in the middle of a long calculation to 
allow the application to respond to user interactions (for example, the user 
might invoke a Cancel button to abort the calculation). 


Note 


The update command can be dangerous, in that it starts an instance of 
Tcl’s event loop. If your script executes an upaate command from within 
an event handler script, it actually starts a nested instance of an event 
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loop that must terminate before the outer event loop regains control. 
This can cause serious problems with your control flow, especially if 
the outer loop was started by a wwait Or tkwait command. If the event that 
they were looking for occurs during the nestea update event loop, they 
don’t “see” the event and so don’t terminate as expected. You should 
avoid nested event loops wherever possible. One approach is to break 
a long-running activity into smaller chunks and have each chunk 
schedule the next chunk to execute via the arter command. Another 
approach is to use the mreaa extension to create a multithreaded Tcl 
application, so that a long-running activity in one thread doesn’t starve 
the event loop in another thread. 


29.4 Information about Widgets 


The winto command provides information about widgets. It has almost 50 
different subcommands for retrieving different kinds of information about a 
widget. For example, winfo exists returns a o or 1 value to indicate whether a 
widget exists. winfo children returns a list whose elements are the children of 
the widget. winfo width and winfo height return the current dimensions of the 
widget. winfo ciass returns the class of the widget, such as sutton OF text. 
Refer to the Tk reference documentation for details on all of the options 
provided by winso. 


29.5 The « Command 


The tx command provides access to various aspects of Tk’s internal state. 
Most everything available from this command pertains to Tk in its entirety, 
the application, or the overall display. 

It can be important to know the windowing system on which your 
application is executing. Historically, people tested the value of the 
::tcl_platform(platform) array element, which Tcl would set to one of windows, 
unix, OF macintosh. However, since the introduction of Mac OS X, this array 
element now (correctly) reports unix for a Mac OS X system. The tx 
windowingsysten Command is now the correct way to determine the windowing 
system. It returns a value of aqua, win32, OF x11. 

tk inactive returns the number of milliseconds since a user last interacted 
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with the system, by moving the mouse, pressing a key, and so on: 


tk inactive 
=> 3 


tk inactive returns -1 if executed in a safe interpreter or on a system that 
doesn’t support querying the inactive time. You can request the idle time of 
a particular display by including the -aispiayor option and specifying the 
name of a window on that display. Additionally, you can include the 
argument reset to reset the idle timer. 

tk scaling returns the scaling factor used when converting between pixels and 
physical units of measure. It’s expressed as a floating-point number, giving 
the number of pixels per typographic point (1/72 inch), and you can use the - 
displayof Option to specify the name of a window on a particular display 
whose scaling factor you want to retrieve: 


tk scaling 
= 1.000492368291482 


Tk does its best to determine the appropriate value when the application 
starts, but systems often don’t provide Tk with a truly accurate value. If an 
accurate scaling factor is important to your application, you should give 
your users some method for calibrating the on-screen measurement. You can 
then pass the new scaling factor to tx scaling aS an argument to set the scaling 
factor of the display for your application. The following example uses the 
winfo screenmmwidth Command to retrieve the calculated width in millimeters of 
a window on-screen: 


winfo screenmmwidth . 
=F Oe 

tk scaling 1.25 

winfo screenmmwidth . 


=> 542 


If your application uses the Tk sena command to send messages to other Tk 
applications, you need to know, and sometimes set, the name of the 
application. The tx appname command returns the current name of the 
application or sets it to a new value. See Chapter 12 for more information 
on the sena command. 


29.6 Variables Managed by Tk 
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Several global variables are significant to Tk, either because Tk sets them 
or because it reads them and adjusts its behavior accordingly. You may find 
the following variables useful: 

® tk library 
Set by Tk to hold the path name of the directory containing a library of 
standard Tk scripts and demonstrations. This variable is set from the 
TK LIBRARY environment variable, if it exists, or from a set of other standard 
locations otherwise. See the txvars reference documentation for a detailed 
description. 

® tk version 
Set by Tk to its current version number. It has a form like s.5, where s is the 
major version number and s is a minor version number. Changes in the 
major version number imply incompatible changes in Tk. 

® tk _patchLevel 
Set by Tk to its current patch level. It has a form like s.5.4, where s is the 
major version number, s is a minor version number, and « is the specific 
patch level. 
In addition to these variables, which may be useful to the application, Tk 
also uses the associative array tx::priv to store information for its private 
use. Applications should not normally use or modify any of the values in 


tk::Priv. 


29.7 Ringing the Bell 


Use the »e11 command to ring the bell, or produce a visual effect, on a given 
display. The basic format is 


bell 


You can also pass the -aispiayor option to define which display should have 
its bell rung: 


bell -displayof window 


With the -nice option, the »-11 command attempts to reset the screen saver on 
the given display, normally making the screen visible again. 
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30. Tcl and C Integration Philosophy 


While it is possible to write a large variety of applications completely in 
Tcl, in some cases it is useful or necessary to combine Tcl and C code, and 
it 1s common to find large applications with portions written in both. 
Where possible, it is almost always best to write Tcl code instead of using 
the C programming language. Tcl programs are easier to write and quicker 
to modify, require less expertise, and are therefore more accessible to other 
programmers. Scripts do not require recompilation after every change and 
are also generally less difficult to debug. However, there are times when 
programming in C is the best choice. 
Fortunately, Tcl makes it very pleasant and productive to combine Tcl and 
C, having been designed with this in mind from the outset. 
The two most common reasons for mixing Tcl and C are 
¢ Adding functionality not available to Tcl, for example, creating a Tcl 
interface to an image manipulation library written in C, or writing 
code to talk to a special device on a Linux system that is accessed 
via specific arguments to the iocti system call. 
¢ Optimizing performance-intensive tasks that must run as fast as 
possible. C is many times faster than Tcl for processor-intensive 
operations, and is therefore the better choice where speed 1s critical. 
Tasks involving extensive numerical computation or manipulation of 
binary-formatted information often benefit from implementation in C 
code. 
This part of the book deals with how to get the best of both worlds by using 
the two languages together, each being used for the part of the application 
for which it is best suited. You will find that it’s easy and a very powerful 
way of programming that can lead to new and innovative applications. 
Programmers generally add C code to Tcl applications by creating their own 
Tcl commands, written in C. These commands then can be bundled into 
extensions, which are loaded into the application as needed. These new 
commands act similarly to any of the built-in Tcl commands or procedures 
that you’ve created, making them easy to control from Tcl. If you are writing 
C code to improve your program’s performance, an intelligent approach to 
optimization is to begin with a program written entirely in Tcl, analyze it for 
slow spots, and then rewrite those spots in C. This 1s a very attractive style 
of developing an application, because it confers on the programmer all the 
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advantages of using a high-level language and concentrates low-level C 
work only where it is absolutely necessary, maximizing both programmer 
time and program efficiency. 

A second approach is to embed Tel in an existing application, a powerful 
technique to enhance your application’s existing capabilities with a 
scripting language. When done properly, this can turn the program into a 
dynamic, configurable system whose behavior may be modified at runtime 
via Tcl scripts, instead of a rigid block of code that must be modified and 
recompiled in order to change its behavior, or at least restarted to reread 
configuration files. As an example, with relatively few lines of C code, the 
Rivet Apache web server module makes it possible to create dynamic web 
pages that rival PHP for speed and ease of web programming. Figure 30.1 
illustrates two methods of integrating C code and Tcl. 


Figure 30.1 Embedding versus extending Tcl 


Embedding Extending 


C C extensions 


application 


There are several parts to most Tcl/C integration projects. The majority of 
the code implements your special-purpose Tcl commands. Then comes the 
startup code that registers those commands with the Tcl interpreter and takes 
care of any other startup tasks such as creating global variables. If you’re 
writing an application that embeds Tcl, at some point you need to write code 
that evaluates Tcl scripts. On the other hand, if you’re writing an extension, 
your C code probably won’t need to evaluate scripts; having the extension 
register its commands with the Tcl interpreter usually is sufficient. 
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30.1 Tel versus C: Where to Draw the Line 


In order to maximize the flexibility of your application, it 1s best to organize 
your C code as a group of primitive operations—basic building blocks, 
flexible enough to be used in different ways—instead of attempting to make 
every possible option available as C code. This makes it possible to mix 
and match these operations in your Tcl scripts. The most important decision 
to make is where to draw the line between having one big, simple command 
that does it all and having many small, very fine-grained commands. If you 
hide too much functionality behind one command, it may not be possible to 
write scripts to combine the functionality in new and interesting ways that 
the original author hadn’t planned for. On the other hand, creating commands 
that are too low-level may not really provide any benefits or added 
flexibility to developers using them. The right point to separate Tcl from C 
is where you have maximum flexibility, but before your Tcl commands 
become a repetitive copy of the C API. 
Tcl’s socket command is a good example of an interface to a complex 
underlying system. It does not mirror the series of C calls necessary to open 
a socket. Instead, all you do is give it an address (which may be a name or 
an IP number) and a port, and it hands you a channel that you can write to or 
read from. More advanced configuration is still possible via the scontfigure 
command, but the basic operation is very easy. 
As another example, consider an array of sensors monitoring some 
information about a production line in a plant, where each sensor takes 
environmental measurements at a different point in the process. Users of 
your interface may wish to perform tasks such as 

¢ Printing a complete report of the current state of the production run to 

a file on disk 

¢ Saving which station has the lowest energy consumption in a database 

¢ Displaying the temperature at station X 

¢ Returning which stations spend more than 25% of their time idle 

¢ Passing the average, high, and low temperatures to a web server 
You'll need to write some C code to access this information, which is 
normally available only as a low-level API provided by the operating 
system. 
One approach might be to write code that reads all information from all 
sensors and dumps it to standard output. It’s certainly a quick approach, but 
it’s not going to be very flexible in the long term and might also be slow, 
depending on access times for the sensors. 
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Another tactic might be to provide Tcl commands to select a sensor, 
determine which information is available, open it for reading, and then fetch 
one measurement. This is certainly flexible, but it’s going to be slow to code 
using the resulting API. 
One way to strike a good balance would be to provide a sensor command 
that takes several arguments: 

* 1ist—returns a list of all sensors 

* reaay—teturns a list of all sensors currently online and transmitting 

data 

* read $sensor—reads and returns the information for a specific sensor 
This would make it easy to use standard Tcl commands like foreach to loop 
through the list of sensors, taking readings from each one. Although the sensor 
command doesn’t return an immediate answer for any of the tasks listed 
previously, it’s possible to use it, together with a bit of scripting, to quickly 
develop solutions for all five problems, and yet it is not too low-level. 
Printing the entire report to a file would be a matter of looping over all 
stations, reading them, and then printing them to a file via the open and puts 
commands. The lowest energy consumption could be determined by looping 
over the online sensors and saving progressively lower values as they 
appear—and at that point the results could be saved to a relational database. 
Displaying one value of the reading for a particular sensor is as easy as 
reading it and saving only the desired information, discarding the rest. 
Collecting statistics on idle stations would, once again, involve reading all 
stations, then looking at one particular value from the collected results. 


30.2 Resource Names—Connecting C Constructs to 
Tel 


One common usage of C extensions is to allow Tcl code to interact with 
complex data structures or objects from either your own application or 
another C library. In your C program, you’d normally refer to this data by a 
pointer to the data structure or object. 

Since everything in Tcl ought to be representable as a string (so we can’t 
use pointers), we need to dedicate some thought to connecting these abstract 
strings with what they represent at the C level—most likely C structures. In 
the example in the preceding section, the sensors might be given names 
relative to their position or function, such as 1-neat, 2-pressure, 3-oxygen. These 
names are brief but descriptive, so that people have an idea of what the 


635 


object might be just by looking at the name. In an example of this system at 
work, Tcl uses names like £i1e1 and sock? for file channel handles and socket 
channel handles respectively. These are simple, clear names that give the 
user an idea that the thing in question is a socket or file. In this case we also 
utilize the POSIX file descriptor number to create a unique name, although 
that information isn’t meant to be used and shouldn’t be relied on at the 
scripting level. In turn, these strings can map to specific structures, most 
likely via a hash table that, for every string input, is able to return a C 
structure of the desired type. Tcl contains a powerful hash table 
implementation that makes this approach easy to implement. See Chapter 40 
for more information on Tcl’s hash table functionality. 


30.3 “Action-Oriented” versus “Object-Oriented” 


There are two approaches to defining commands in an application: “action- 
oriented” and “object-oriented.” In the action-oriented approach, commands 
are defined that act on objects passed to them as parameters; for instance, 
Tcl’s commands for manipulating files all take a file identifier returned by 
open aS an argument and proceed to perform some action on it: 


set fid [open "/tmp/foobar" w] 
fconfigure $fid -translation 1f 
puts $fid "Some text" 


close Sfid 


In contrast, the “object-oriented” style provides one command whose only 
job is to represent the object directly. In this case, there are many Tcl 
commands that can be called: one for each object, and one to create new 
objects. In retrospect, it might have been more logical to adopt this style for 
files: you would create a file with open, and then use it as a command, as 
here: 


set fid [file "/tmp/foobar" w] 
$fid fconfigure -translation lf 
Sfid puts "Some text" 


Sfid close 


Despite appearances, remember that commands created in this way are just 
regular Tcl commands. While in many ways they act similarly to objects in 
languages like Smalltalk, Ruby, or Java (that is, the subcommands look like 
“methods”; most of them have some data associated with them; etc.), they 
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actually are procedural commands; they do not have inheritance or support 
other features of true object-oriented programming. There are other ways 
(several, in fact) to create objects in Tcl based on classes, methods, 
inheritance, and so on. 
The action-oriented style is best when 
¢ There are a large number of resources (e.g., strings or integers), so it 
would be wasteful to create a command for each one. 
¢ The resources are short-lived, so setup and tear-down time for the 
object would be more effort than it was worth. 
¢ A command accepts many types of objects as parameters and 
executes the same code on all of them. For example, the cestroy 
command in Tk works on all widget types, so it’s best to keep all the 
functionality in one place, instead of giving every widget a cestroy 
subcommand. 
Our sensor-monitoring example uses this approach because there may be a 
large number of sensors to watch, and there are not many actions that may be 
performed on each one. In the case that not all sensors are read constantly, it 
makes even more sense to use the action-oriented approach, so that the 
program does not have to maintain information for each one all the time but 
only when requested. 
Using the “object-oriented” approach works well when 
¢ There are not too many objects (tens or hundreds). 
¢ The objects are well defined. 
¢ They are likely to be in existence and used for a reasonable duration. 
¢ They are reasonably complex, with a number of operations that may 
be performed on them. 


30.4 Representing Information 


The information passed into and out of your Tcl commands should be 
formatted for easy processing by Tcl scripts, not necessarily for maximum 
human readability. The sensor monitor commands should not return a 
description of the sensor status like not, real not, OF The temperature is 70 c, OF 
a even nicely formatted table ready for printing, but rather results easily 
passed to and consumed by other Tcl commands. Should you need to 
structure the data in some way, you can create Tcl lists and arrays (or 
dictionaries in Tcl 8.5) from C. As an aid to other programmers or 
consumers of your data, it is preferable to make your data self-descriptive 
enough that you don’t leave people wondering about what position in a list 
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corresponds to what value. For instance, the list i105 s9 96 tells us nothing by 
itself. If we use a dictionary like max 105 min 89 average 96, the data makes 
much more sense at a glance, and yet it is still very easy to manipulate from 
Tel. 
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31. Interpreters 


This chapter explains what interpreters are, how to create them and delete 
them, and how to use them to evaluate Tel scripts. 


31.1 Functions Presented in This Chapter 


© Tcl Interp *Tcl CreateInterp() 


Creates and returns a new Tcl interpreter. 


* Tcl DeleteInterp(Tcl Interp *interp) 


Deletes a Tcl interpreter. 


* Tcl _InterpDeleted(Tcl Interp *interp) 


Returns nonzero if the interpreter is slated for deletion. 


en 


cl Interp *Tcl CreateSlave(Tcl Interp *interp, 
CONST charslaveName, int isSafe) 
Creates a “slave” interpreter with the name siavename. The issare parameter 
determines whether to create a safe interpreter or not. 
int Tcl_IsSafe(Tcl_Interp *interp) 
Returns : if the interpreter is safe, otherwise o. 


int Tcl MakeSafe(Tcl Interp *interp) 
Transforms the interpreter into a safe interpreter, removing any “dangerous” 
commands and variables. Does not remove commands from extensions, so 
simply calling this function is not a guarantee of safety. 

* Tcl _Interp *Tcl_GetSlave(Tcl_Interp *interp, 
CONST char *slaveName) 


Returns the slave interpreter of intero named by siavename. 


* Tcl _Interp *Tcl_ GetMaster (Tcl Interp *interp) 
Returns the master of the given slave interpreter. 


° int Tcl GetInterpPath(Tcl_ Interp *askingInterp, 
Tcl _Interp *slaveInterp) 
Sets the result in askingInterp tO the path between askingInterp and slaveInterp. 


Returns rct_ox, OF tcL_eRRor 1f the path cannot be computed. 


int Tcl HideCommand(Tcl_ Interp *interp, 

CONST char *cmdName, CONST char *hiddenCmdName) 
Moves cmavame to the set of hidden commands, giving it the name niadencmaname. 
If cmanvame doesn’t exist as a visible command, rcz error 1S returned. 
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* int Tcl ExposeCommand (Tcl Interp *interp, 
CONST char *hiddenCmdName, CONST char *cmdName) 
Moves the hidden command referred to by niadencmaname to the visible 
command cmaname. Returns tct error if the command doesn’t exist. 


® int Tcl CreateAlias (Tcl Interp *slaveInterp, 


CONST char *slaveCmd, Tcl_Interp *targetInterp, 


CONST char *targetCmd, int argc, 


CONST char **argv) 


int Tcl_CreateAliasObj(Tcl_Interp *slaveInterp, 

CONST char *slaveCmd, Tcl_Interp *targetInterp, 

CONST char *targetCmd, int objc, 

Tcl Obj **objv) 
These two commands are essentially the same, the difference being that 
Tcl_CreateaAliasobj takes an array of Tcl objects instead of strings, for the sake 
of efficiency. Both commands create a command siavecma IN silavernterp, 
aliasing it to targetcma IN targetinterp. The arguments in argv Or objv are 
prefixed to any arguments passed to the command alias. 

® int Tcl _GetAlias(Tcl_Interp *interp, 
CONST char *slaveCmd, Tcl_Interp *targetInterpPtr, 


CONST char *targetCmdPtr, int *argcPtr, 


CONST char ***argvPtr) 


int Tcl _GetAliasObj (Tcl_Interp *interp, 
CONST char *slaveCmd, Tcl_Interp *targetInterpPtr, 


CONST char *targetCmdPtr, int *objcPtr, 

Tol Obj ***objvPtr) 
Both of these functions obtain information about an aliased command by 
looking up an alias siavecma IN interp and filling in the targetinterpptr, 
targetcmaPtr, a pointer to the number of arguments, and then either opjveer or 


argvPtr. 


31.2 Interpreters 


The central data structure used by the Tcl library is a C structure of type 
tcl_tnterp. Throughout this part of the book we’ll refer to these data 
structures as interpreters. An interpreter embodies the execution state of a 
Tcl script, including Tcl procedures, commands implemented in C, 
variables, and an execution stack that reflects the internal state of command 
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and script evaluation. It is, ina sense, the world in which a Tel script is run, 
and Tcl scripts cannot see outside the interpreter they are in. The interpreter 
keeps track of where it is in the script being evaluated, what commands are 
available to be called, as well as the variables that have been set within it. 
Most of the Tcl library procedures take a pointer to a 1c1_tnterp Structure as 
an argument. 

Tcl applications often use only a single interpreter; however, it is possible 
for a single process to manage several independent interpreters. As an 
example, consider a server that responds to requests from different clients 
by executing some Tcl code when it receives a network connection. Each 
interpreter could be responsible for executing code from a specific client, 
and since different interpreters are used, their data is not visible to one 
another, even though they reside in the same address space. Keep in mind 
that multiple interpreters are not multiple threads, though, and so do not 
resolve problems of concurrency. In order to learn about concurrency 
issues, see Chapter 43 on events and Chapter 46 on threads. 

If you embed Tcl in your own code, you are responsible for creating one or 
more interpreters. If you write a Tcl extension, when it is loaded, Tcl add 
the extension’s commands and variables to those in the interpreter in which 
itis loaded. 


31.3 A Simple Tel Application 


Up until now you’ve run Tcl programs by using the tcisn or wisn binaries, but 
of course that’s not the only way. 

The following program illustrates how to create and use an interpreter. It is 
a simple but complete Tcl application that evaluates a Tcl script ina file and 
prints either the results or, in the case of an error, the error message. 
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#include <tcl.h> 

int main(int argc, char *argv[]) { 
Tcl _Interp *interp; 
char *result; 
int code; 


if (arge != 2) { 
fprintf(stderr, 
"Wrong number of arguments: "}); 
fprintf(stderr, 
"should be \"%s filename\"\n", argv[0]); 
exit (1); 


} 


interp = Tcl CreateInterp(); 
code = Tcl _EvalFile(interp, argv[1]); 
result = Tcl _GetStringResult (interp) ; 


if (code != TCL_OK) { 
printf("Error was: %s\n", result); 
exit (1); 


printf ("Result was: ts\n", result); 
Tcl DeleteInterp(interp) ; 
exit(0); 


} 


If you have a complete installation of Tcl, compiling this code should be 
relatively easy, something along the lines of 


cc -o simple simple.c -ltcl8.5 


on a Debian Linux system. Depending on your installation of Tcl, you may 
need to add flags such as -t/usr/inciude/tcis.5 Which is necessary, for 
example, on Debian Linux systems. For more information on building Tcl 
applications and extensions, see Chapter 47. 

You can now use your program to run Tcl scripts, like so: 


./simple hello.tcl 


Let’s go back and look at simpie.c. For this simple example, we do not need 
to include any headers besides tci.n, which already includes many other 
headers in turn. Logically, whenever you use Tcl, you need to include tc1.n. 
In the main function, we create a pointer to an interpreter, a return code 
integer, and a pointer to a result string. 

We then make sure that we have an argument to our program—the file 
containing the Tcl script to evaluate. Next, we create the interpreter. This 
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new interpreter contains all the built-in commands defined in the Tcl library 
(1ibtcis.5.so In this case), but few of the Tcl procedures or variables that 
standard tcisn has, because we do not load the standard initialization scripts. 
For information on which variables are present where, see the tcivars and 
tcish reference documentation. After the file is evaluated, two pieces of 
information are available: first, the return code from rc1 Evairile, Which is an 
int that corresponds to rczt_ox 1f everything went well, or tc. srror if there 
Was a problem, or any one of TCL RETURN, TCL BREAK, OL TCL CONTINUE for other 
various conditions. To get the result in string form, or an error string, we 
call tc1_cetstringResuit and then, depending on whether it’s an actual result or 
an error condition, print something to that effect. 

See Chapter 33 for more ways of evaluating Tcl code from your own 
applications and extensions. 


31.4 Deleting Interpreters 


When a Tel interpreter is no longer needed, it may be deleted with the 
Tcl_DeleteInterp Call. This frees the interpreter and everything associated with 
it, including variables, commands, and file descriptors that are not shared 
with other interpreters. 


31.5 Multiple Interpreters 


One of Tcl’s most interesting features is the ability to have multiple 
interpreters present and active. See Chapter 15 for a discussion of 
manipulating multiple interpreters from Tcl scripts. As stated above, 
multiple interpreters are not a mechanism for concurrency; however, they 
are very useful for isolating code that must be run separately. The basic 
mechanism for creating subinterpreters (also known as slaves) is the 
Tcl_Createsiave function, which is used as in the following example: 
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char +interp_names iT = "a", "bh" , "e®, nq , "er", nent ; 


f 


int 


for 


} 


The loop creates a series of slave interpreters, each of which has a port 
defined on which to listen, so that the Tcl code can listen on a separate port 
for each one. If you are very sure of who you are connecting with, you could 
even evaluate code sent over the socket and return the results, and problems 
in one interpreter would not spill over into the others. tc1_createsiave takes a 
Tcl interpreter, name, and finally an integer specifying whether to make the 


/* Port numbers to use for interpreters. */ 


interp ports[] = {10000, 10001, 10002, 
10003, 10004, 10005}; 
(i = 0; i < NUM_INTERPS; i++) { 


/* Create a slave interpreter. */ 

slave _interps[i] = Tcl CreateSlave( 
interp, interp names[i], 0); 

/* Set the 'port' variable in the slave 
interpreter. */ 

Tcl SetVar2Ex(slave interps[i], "port", NULL, 
Tcl NewIntObj(interp ports[i]), 0); 

/* Run the script in the new slave interpreter. 

Tol EvalFile(slave_interps[i], argv[1]); 


slave a safe interpreter or not. 
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32. Tcl Objects 


In Tcl, all values can be treated as strings. Early versions of Tcl actually 
stored all values as strings, even numeric data types. This approach could 
be quite slow, especially for values that needed frequent conversion to 
binary formats, such as floating-point numbers. 

In contrast, all modern versions of Tcl (ever since 8.0, released in 1997) 
store their data internally using a much more efficient form called 7c/ 
objects. Tcl objects are values that have a string representation and a 
second “internal” representation of some other type, such as integer, double, 
list, or, in Tcl 8.5, dictionaries. Tcl uses objects internally for variable 
values, command arguments, command results, and scripts. 

This dual nature of Tcl objects means that they are fast where they need to 
be, efficient in terms of memory, and still easy to work with. For example, 
in a while loop with a counter variable, the variable is transformed into an 
integer and remains an integer for the duration of the loop. This makes the 
Tcl code much more efficient than having a string that is constantly being 
transformed to an integer and back, each time it is incremented. 

Since objects are a newer addition to Tcl, for many operations there are two 
API calls: one that uses objects, and one that uses the string-based interface. 
The older API is simpler, but at the cost of speed, especially where numbers 
are concerned. 

Tcl objects are represented at the C level by the rc1_ ov} structure: 


Tel_Obj *obj = Tcl NewObj(); 


This code creates a new, empty object. In most cases, you should view this 
aS an opaque type—you don’t need to deal with the structure’s members, 
because the Tcl API does that for you. 


32.1 Functions Presented in This Chapter 


® Tcl Obj *Tcl_NewObj () 
Creates a new object. 
* Tcl Obj *Tcl_ DuplicateObj (Tcl Obj *objPtr) 
Returns a new copy of the object, with reference count 0. 
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® Tcl_IncrRefCount (Tcl Obj *objPtr) 
Increases the object’s reference count. 
® Tcl DecrRefCount (Tcl Obj *objPtr) 
Decreases the object’s reference count and frees it if the reference count 
goes to 0 or less. 
® int Tcl IsShared(Tcl_ Obj *objPtr) 
Returns : if the object is shared, o otherwise. 
* Tcl _InvalidateStringRep (Tcl Obj *objPtr) 
Marks the object’s string representation as invalid and frees space 
associated with it. 
* Tcl Obj *Tcl_NewBooleanObj (int boolValue) 
Creates a new object with an initial value pooivaiue. 


* Tcl Obj *Tcl_ NewIntObj (int intValue) 
Creates a new object with an initial value intvaiue. 
* Tcl Obj *Tcl_ NewLongObj (long longValue) 
Creates a new object with an initial value tongvaiue. 
* Tcl Obj *Tcl_ NewWideIntObj (Tcl WideInt wideValue) 


Creates a new object with an initial value wicevatue. 


* Tcl Obj *Tcl_ NewBignumObj (mp int *bigValue) 
Creates a new object with an initial arbitrary-precision integer value 
bigValue. 

* Tcl Obj *Tcl_NewDoubleObj (double doubleValue) 
Creates a new object with an initial value doubievaiue. 


* Tcl Obj *Tcl_ NewStringObj (const char *bytes, int length) 
Creates a new object with an initial value of the UTF-8 string from bytes. 
Only the first iengtn bytes are copied, unless 1engen is negative, in which case 
all bytes up to the first null character are copied. 

* Tcl Obj *Tcl_ NewByteArrayObj (CONST unsigned char *bytes, 

int length) 

Creates a new byte array object from bytes. 

® Tcl SetBooleanObj (Tcl Obj *objPtr, int boolValue) 
Sets the existing object onjrer to Boolean pooivaiue. 

* Tcl SetIntObj (Tcl Obj *objPtr, int intValue) 
Sets the existing object onjrtr tO intvaiue. 

* Tcl _SetLongObj (Tcl Obj *objPtr, long longValue) 
Sets the existing object onjrer tO 1ongvalue. 

* Tcl SetWideIntObj (Tcl Obj *objPtr, Tcl WideInt wideValue) 
Sets the existing object onjrtr tO widevalue. 

* Tcl SetBignumObj (Tcl Obj *objPtr, mp int *bigValue) 
Sets the existing object opjrrr to the arbitrary-precision integer value 
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bigValue. 
® Tcl _SetDoubleObj (Tcl Obj *objPtr, double doubleValue) 
Sets the existing object onjrtr tO doublevalue. 


* Tcl SetStringObj (Tcl Obj *objPtr, const char *bytes, 


int length) 
Sets the existing object opjrer to the value of the UTF-8 string from pyres. 
Only the first iengtn bytes are copied, unless tengen is negative, in which case 
all bytes up to the first null character are copied. 
* void Tcl SetByteArrayObj (Tcl Obj *objPtr, 
CONST unsigned char *bytes, int length) 
Sets the object to be a byte array containing bytes. 
® unsigned char *Tcl SetByteArrayLength (Tcl Obj *objPtr, 
int length) 
Sets the length of the byte array, truncating it or extending it (with arbitrary 
values), and returns the object’s new array of bytes. 
* int Tcl _GetBooleanFromObj (Tcl _Interp *interp, 
Tcl_Obj *objPtr, int *boolPtr) 
Gets the Boolean value of o»jrer and places it in booirer. Returns tc. error ON 
failure. 


int Tcl _GetIntFromObj (Tcl Interp *interp, 

Tcl Obj *objPtr, int *intPtr) 
Gets the integer value of onjrer and places it in inteer. Returns tci error ON 
failure. 


int Tcl_GetLongFromObj (Tcl_Interp *interp, 

Tel Obj *objPtr, long *longPtr) 
Gets the long value of ovjrer and places it in inteer. Returns tect error On 
failure. 


* int Tcl _GetWideIntFromObj (Tcl _Interp *interp, 


Tcl Obj *objPtr, Tcl WideInt *widePtr) 
Gets the wide integer value of o»jrcr and places it in inteer. Returns tc. error 
on failure. 


int Tcl _GetBignumFromObj (Tcl _Interp *interp, 

Tcl Obj *objPtr, mp int *bigValue) 
Gets the arbitrary-precision integer value of onjrer and places it in bigvatue. 
Returns rc. error on failure. 


int Tcl_GetDoubleFromObj (Tcl _Interp *interp, 
Tcl Obj *objPtr, double *doublePtr) 

Gets the double value of o»jrer and places it in doupiertr. Returns cr error ON 

failure. 


® char *Tcl_ GetStringFromObj (Tcl Obj *objPtr, 
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int *lengthPtr) 
Returns a pointer to the object’s string representation and places the length 
of the string in tengenrer if 1t is non-null. 
* unsigned char *Tcl_ GetByteArrayFromObj (Tcl Obj *objPtr, 
int *lengthPtr) 
Returns the bytes contained in a byte array object and places the length of 
the bytes in iengtnper if it is non-null. 
® char *Tcl Alloc(int size) 
char *Tcl_ AttemptAlloc(int size) 
char *ckalloc(int size) 
char *attemptckalloc(int size) 
Returns a pointer to a block of at least size bytes suitably aligned for any 
use. Use these routines rather than the native maiioc. tcl _attemptalloc does not 
cause the Tcl interpreter to panic if the memory allocation fails, whereas 
Tol Alloc GOES. ckalloc ANd attemptckalloc are macros equivalent to their 
corresponding functions, except they also support advanced memory 
debugging. See the reference documentation for more information. 
® char *Tcl Realloc(char *ptr, int size) 
char *Tcl AttemptRealloc(char *ptr, int size) 
char *ckrealloc(char *ptr, int size) 
char *attemptckrealloc(char *ptr, int size) 
Changes the size of the block pointed to by per to size bytes and returns a 
pointer to the new block. The contents are unchanged up to the lesser of the 
new and old sizes. The returned location may be different from per. 
Tcl_AttemptRealloc does not cause the Tcl interpreter to panic if the memory 
allocation fails, whereas tc1 Realloc GOES. ckrealloc aNd attemptckrealloc are 
macros equivalent to their corresponding functions, except they also support 
advanced memory debugging. 


® Tcl Free(char *ptr) 


ckfree(char *ptr) 
Makes the space referred to by per available for further allocation. cxrree 1s 
an equivalent macro that also supports advanced memory debugging. 


32.2 String Objects 


Since all Tcl objects may be represented as strings, we will begin our 
exploration of Tcl objects with them. 
To create a new string object: 
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Tel Obj *strobj; 
strobj = Tcl_ NewStringObj("Tcl!", -1); 


A new string object is created from a series of bytes (in the UTF-8 encoding 
—see Chapter 39 for more information about encodings) and their length. In 
this case, the -1 value means that we let Tcl determine the string length 
instead of specifying the value ourselves, which is often a handy shortcut. 

Strings and commands to manipulate them are covered in more detail in 


Chapter 39. 


32.3 Numerical Objects 


Creating an object that contains an integer is similar: 


Tel_Obj *intobj; 
intobj = Tcl NewIntObj(42); 


This version of intopj 18 far more efficient to use in mathematical operations 
than a string representation of the number 42, because it contains an actual 
integer as its internal representation. 
Other numerical types that can be created are the following: 
* Boolean—Either true or false, i or o. Created’ with 
Tcl _NewBooleanObj (int). 
¢ long—Holds a long integer. Created with 1c1_Newtongop; (ong) . 
¢ wide—Holds a “wide” (64-bit) integer. Created with 
Tel NewWideIntObj (widevalue), Where widevalue 18 at least a 64-bit value. 
¢ bignum—Holds an arbitrary-precision integer. Created with 
Tcl_NewBignumObj (bigvalue), Where pigvalue 18S a pointer to an mp int 
structure as declared by the LibTomMath arbitrary-precision integer 
library. 
* double—cContains a C double type. This is the type Tcl uses to deal 
with floating-point numbers. Created with tc1_Newdoub1eon; (double) . 


32.4 Fetching C Values from Objects 


To use a Tcl object in your C code, you'll need to retrieve its underlying 
value, whether a string, an integer, a double, or some other format. Your 
program asks the Tcl library to translate a given object into the type you 
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need. This may be directly accessible from the string or internal 
representation, or some conversion may need to be done (e.g., retrieving a 
double value from an object having an integer internal representation). 
While Tcl guarantees that any arbitrary object can be retrieved as a string, 
this is not true for other data types. Note also that by asking for a value as a 
specific type, Tcl modifies the internal representation to be that type—if, of 
course, it was possible to perform the requested fetch. For example, if an 
object contains an integer internal representation, and 1c1_ cetdoublerromobj 18 
called on it successfully, the new internal representation is a double. 

It is always possible to transform an object into a string, using the 
Tcl_GetStringFromobj Call, but it may not necessarily be possible to transform 
an object into other types, such as integer, double, and so on. For this 
reason, tci_ GetIntFromopj and the other calls to obtain various types from Tcl 
objects take an interpreter as an argument, so that they may raise an 
exception should they encounter a problem transforming the object into the 
desired type. 


char *intstring; 
intstring = Tcl _GetStringFromObj (intobj) ; 
/* No problem. */ 


int stPint? 
Tcl Obj *strobj; 
strobj = Tcl NewStringObj("Tcl!", -1); 


Tcl GetIntFromObj(interp, strobj, &strint); 
/* Fails! */ 


In the first case, the call to 1ci_cetstringFromobj 18 always successful, because 
by their very nature, Tcl objects can always be represented as strings 
—intstring 18 42. However, the call to tc1 cetintrromobj does return an error, 
because we attempt to call it with the object stronj. This object contains the 
string tci!, which cannot be transformed into an integer, and so a tct_ERRoR 
result is returned, and an error message is left in the interpreter. As with 
object creation, functions exist for all types in order to attempt to extract the 
type in question from the Tcl object—for example, tc1_cetLongrromops, 
Tcl_GetDoubleFromobj, and so on for the numerical types. 


32.5 The Dynamic Nature of a Tcl Object 


To illustrate the dual nature of a Tcl object, let’s examine its life in a Tcl 
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script: 

1. set foo 35100 

2. puts “The wAliie of \Sf00 is: S£00" 

3. incr foo 100 

4. puts "Now \$fo00 is: $foo" 
On line 1, the variable soo is set to an object containing the characters 35100. 
At this point, the object 1s a string. 
When the script on line 2 prints the variable foo, its string value is needed, 
and 35100 1s used. 
The object that s.o contains is transformed in line 3. Whereas it was 
previously a string, we now wish to increment its value by 100, so we need 
to deal with it as a number. As it is not currently a number, it is set to the 
integer type, and its internal representation is set to 35100. The incr 
command then acts on this integer, incrementing it to 35200. The string 
representation of the object is marked as invalid, but a new string 
representation is not generated at this time; regenerating the string 
representation could be wasted effort if the object is changed by further 
arithmetic operations. 
On the final line, we print the value of roo again. Its string representation is 
not currently valid, so we update it to 35200, which the puts command then 
prints. At the end of the script, the object contains both a valid string 
representation and the integer 35200. 


32.6 Byte Arrays 


Byte arrays exist to hold arbitrary sequences of 8-bit values that do not 
necessarily correspond to characters as string objects must. Byte arrays are 
useful for holding binary data—such as a JPEG or an MP3 sound file—that 
might contain embedded nulls. 


unsigned char jpegheader[11] = 
{Oxff, Oxff, Oxd8, Oxff, Oxe0, 0x00, 
0x10, Ox4a, 0x46, 0x49, 0x46}; 

Tel Obj *byteobj; 


byteobj = Tcl NewByteArrayObj (jpegheader, 11); 


This example creates a Tcl object that represents the first bytes of a JPEG 
file header. 
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32.7 Composite Objects 


Prior to Tcl 8.4, Tcl had one type of object that could contain other objects: 
a list. From the perspective of C, lists are Tcl objects that contain an array 
of other Tcl objects. Manipulating lists from a Tcl script is discussed in 
Chapter 6. Tcl’s C API lets you do everything you can do from Tcl and is 
covered in further detail in Chapter 41. 

As of version 8.5 (although there is also a backport available for 8.4), Tcl 
also provides dictionary objects (also referred to as dict objects) that 
reference other objects through a hash table. The Tcl script commands for 
interacting with dictionary objects are discussed in Chapter _7. The C 
interface allows you to do many of the same things and is covered together 
with lists in Chapter 41. 

Tel lists and dictionaries are good ways of passing more complex structures 
back and forth between Tcl and C, as we saw in the section on representing 
information in Chapter 30. Lists are best suited for situations where 
elements are accessed via a numerical index (fetch element 5, for instance), 
whereas dictionaries are efficient when looking up an object based on a 
string describing it, for instance, mapping “Rome” to “Italy,” “Paris” to 
“France,” “Berlin” to “Germany,” and so on. 


32.8 Reference Counting 


To avoid creating unnecessary copies of an object, many parts of your 
application may share the same Tcl object at the same time. For example, a 
single Tcl object might be used in a procedure, stored in a variable, used 
within the Tcl library itself, and so on. In order to manage objects and the 
memory they consume, Tcl uses a technique called reference counting. 
Reference counting solves the same basic problem as garbage collection in 
languages like Scheme, Ruby, or Java. It is robust, fast, straightforward, and 
portable, and it makes working with Tcl at the C level simple. 

A newly created Tcl object has an initial reference count of 0. Any code that 
needs to mark the object as being in use should increment the reference 
count of the object using the tc1 tncrrefcount function. When the code no 
longer needs the object, it should decrement the reference count with 
Tcl_DecrRefCount. Once the reference count of an object is decremented to 0 or 
less, Tcl can free the object. 
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Many Tcl functions temporarily modify the reference counts of object that 
you provide as arguments. If your code creates a new object (with a 
reference count of 0), and then passes it to a Tcl function without first 
incrementing its reference count, the Tcl function could internally increment 
and later decrement the reference counter of the object you provided. The 
function’s internal decrement of the object’s reference count back to 0 
would trigger the deletion of the object. Subsequent attempts to use the 
object in your code would of course result in an error. 

Generally speaking, you should increment the reference count of any newly 
created object and then decrement the reference count when the pointer 
variable goes out of scope. However, there are a few Tcl functions that store 
a new reference to an existing object that you provide, incrementing the 
object’s reference count. These functions handle putting an object in a 
variable, storing it in a list or dictionary object, or putting it in the 
interpreter’s result. (All of these actions are discussed in subsequent 
chapters.) If you create an object only to pass it to one of these functions, 
it’s safe to omit the tci_tnerrefcount/Tcl_DecrRefCount Of the object. 


32.9 Shared Objects 


Tcl implements a “copy-on-write” system for objects. This means that an 
object may be shared among several variables, for instance, as long as none 
of them is written to. Once a write occurs, a copy of the object is made. 
What this signifies when you are writing C code for Tcl is that when directly 
modifying an object, you need to check to ensure that it’s not shared via the 
Tcl_Issharea function, and if it is shared, copy it using tc1_puplicateod): 


if (Tcl_IsShared(objPtr)) { 


objPtr = TclDuplicateObj (objPtr); 


/* objPtr now points to a duplicate of the original 
* object, with a reference count of 0. 
* / 

} 

f 
Commands that need this check are usually those that access and modify an 
object that’s the value of a variable, like incr and 1appena. This bit of Tcl 
code illustrates an object that is at first shared and subsequently copied 
when modified: 
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set foo 1 


set bar Sfoo; 


# foo and bar share the same object - 'l'. 
incr bar; 
# bar now has its own object - '2'. 


Initially, an object containing 1 is created and assigned to the ¢oo variable. 
Then, the same object is assigned to the par variable. At this point, both 
variables refer to one object, whose value is 1. The next command, incr par, 
notices that the value is shared, makes a copy, and increments the value of 
the copy. The ¢.o variable now contains an object with the value 1, and bar 
contains an integer object with the value 2. If we were to evaluate incr par a 
second time, tc1_tssharea Would return false, because the object is now 
distinct from that contained in foo. 


32.10 New Object Types 


Since they are rarely needed, we won’t cover them in much depth here, but 
you should be aware that if the need arises, it is possible to create new 
object types via Tel’s C API. 

Creating a new object type makes sense where the object is easily 
represented as a string that may be converted to the type in question and then 
back again without losing information. For more complex C data structures, 
a better approach is the technique of mapping the structure to a unique tag 
via a hash table, mentioned in Section 30.4. 

We must also ensure that if a user modifies the object value as a string, 
nothing bad will happen if we transform it back to the type in question. 
Consider what would happen if we were to create a Tcl “reference” object 
type that contained a C pointer, say, 0x10001800. If the user modified it, as a 
string, to be )oxi0001810, and then tried to use it again as a pointer type, the 
most likely result would be a segmentation fault or data corruption. 

The most sensible reason to create a new Tcl object type is for simple (not 
represented as a complex structure in C) new data types that need to 
efficiently represent information and don’t have problems representing it as 
a string. 

A good example of how to create a new data type is provided by Salvatore 
Sanfilippo’s tcisbignum package, which provided arbitrary-precision integer 
math capabilities prior to Tcl 8.5’s native signumon; support. 

The core of a new type is the rc1_objrype structure: 
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typedef struct Tcl_ObjType { 
char *name; 
Tcl _FreeInternalRepProc *freeIntRepProc; 
Tcl DupInternalRepProc *dupIntRepProc; 
Tcl UpdateStringProc *updateStringProc; 
Tcl SetFromAnyProc *setFromAnyProc; 

} Tcl_ObjType; 


When creating a new type, the programmer supplies functions that 

¢ Free the storage of the type via the tc1_rreetnternalreprroc Slot. In the 
bignum library, this just means freeing the associated memory. 

¢ Make a copy of the object via the tc1_pupinternalrepProc Slot. If the type 
is a data structure, it is up to the programmer to decided whether to 
make a “deep copy” or not. By deep copy we mean copying the 
entire data structure, not just the top, or head. For instance, when 
copying a list, you could make a copy of the list structure itself and 
leave the elements pointing to the same objects, or you could make 
copies of all the elements as well (and so on recursively if the 
elements are in turn lists). This is a deep copy. In reality, Tcl list 
copies are not deep copies. In the bignum library, the bignum value 
is copied. 

¢ Update the object’s string representation to match the current value of 
the object via the tc1_upaatestringproc Slot. The bignum library’s string 
update function fills in the string representation with a base 10 
representation of the number. 

¢ The opposite transformation—tre-creating the internal representation 
from a string—is performed by the setrromanyrroc function slot in the 
Tcl_Objtype Structure. In this case, the bignum library must parse the 
string into a number, or return an error if it is unable to do so. 


32.11 Parsing Strings 


Prior to the advent of Tcl objects, when everything was represented as a 
string internally, it was necessary to be able to easily obtain other types 
from those strings by parsing them. Tcl still provides those calls, and they 
are occasionally handy when working with strings: 
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int Tel GetInt (Tcl Interp *interp, CONST char *string, 
int *intPtr); 

int Tcl GetDouble(Tcl Interp *interp, 
CONST char *string, int *doublePtr); 

int Tcl GetBool(Tcl Interp *interp, CONST char *string, 
int *intPtr); 


These calls all take an interpreter and a string containing the information to 
be parsed as arguments, as well as a pointer to a C variable of the desired 
type, with a Boolean being either : or o. On success, they return tci_ox, and 
on failure, tct_=rror; for instance: 


int num = 0; 
Tel_GetInt(interp, "42", &num); 


This code sets num to 42 and returns tc ox. 


32.12 Memory Allocation 


Tcl provides, as you will see in later chapters, many functions to perform 
common actions in a uniform, cross-platform manner. One of the most 
important activities for which Tcl provides a layer is memory allocation. To 
allocate and free memory in Tcl, we use tci alloc and tci Free. These 
functions are equivalent to maiioc and free in C, but be careful not to mix and 
match them, such as calling tci rree on memory allocated with maiicc or 
strdup, because on some platforms with certain Tcl configurations, this 
causes problems. Additionally, Tcl provides the rci_ Rreaiicc function, to use 
instead of reaiioc, to change the size of an allocated block of memory. The 
location returned may be different from the original location, but the 
contents of the block are unchanged up to the lesser of the old and the new 
Sizes. 

Tcl _Alloc aNd tcl _Realloc cause the Tcl interpreter to panic if the memory 
allocation fails. To avoid this, you can call ci attemptailoc and 
Tcl_AttemptRealloc Instead, which simply return nox 1f they fail. 

Corresponding to all of these functions is a set of macros: ckalloc, ckfree, 
ckrealloc, attemptckalloc, ANd attemptckrealloc. Normally, they are synonyms for 
the corresponding procedures described previously. However, when Tcl 
and all modules calling Tcl are compiled with rc1 =m peeve defined, these 
macros are redefined to be special debugging versions of these procedures. 
This enables the memory ensemble for tracking and reporting memory 
allocation. See the memory reference documentation for more information. If 
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you anticipate requiring memory debugging of your code, you should use 
these macros instead of direct calls to rc1 aiioc and the other functions. 
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33. Evaluating Tcl Code 


This chapter illustrates how to evaluate Tcl scripts from your C code, as 
well as Tcl math expressions. 


33.1 Functions Presented in This Chapter 


Paint Tcl EvalObjEx(Tcl_Interp *interp, 
Tcl Obj *objPtr, int flags) 
Evaluates a Tcl script contained in an object. 


* int Tcl EvalFile(Tcl Interp *interp, 
CONST char *fileName) 
Evaluates a Tcl script in a file given by fiiewame. 


® int Tcl EvalObjv(Tcl_Interp *interp, int objc, 
Tcl Obj **objv, int flags) 
Executes a single preparsed command instead of a script. The ovjc and opjv 
arguments contain the values of the words for the Tcl command, one word in 
each object in opjv. 
int Tcl Eval(Tcl_Interp *interp, CONST char *script) 


Evaluates s cript. 


int Tcl EvalEx(Tcl_Interp *interp, 


CONST char *script, int numBytes, int flags) 
Evaluates script. More efficient than tc1_svai. 


* int Tcl GlobalEval(Tcl_ Interp *interp, 
CONST char *script) 
Evaluates script in the global namespace. Deprecated. 


© int Tcl GlobalEvalObj (Tcl_Interp *interp, 


Tcl Obj *objPtr) 
Evaluates the script in o»jrtr in the global namespace. Deprecated. 


® int Tcl VarEval(Tcl_Interp *interp, char *string, 


char *string, ... (char *) NULL) 
Takes any number of string arguments of any length, concatenates them into a 
single string, then evaluates that string. Deprecated. 


© int Tcl VarEvalVA(Tcl_ Interp *interp, 


va_list argList) 


Like tc1_varevai, but takes a va _1ist instead of multiple strings. Deprecated. 
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* Tcl Obj *Tcl_ GetObjResult (Tcl Interp *interp) 
Returns the result for interp as an object. The object’s reference count is not 
incremented. 

e 


const char *Tcl_ GetStringResult (Tcl_Interp *interp) 
Returns the result for interp as a string. 


33.2 Evaluating Tcl Code 


In Chapter 31 we saw the use of tc1_Evairiie to evaluate a Tcl script ina file. 
Tcl provides several other functions for evaluating scripts. These functions 
all take an interpreter as their first argument, return a completion code, and 
set a result in the interpreter. The most direct of these 1s tc1_zva1: 


Tel .Ob]; *résult; 
char script{] = "set a [expr {20 * 30}]"; 


code = Tcl Eval(interp, script); 
result = Tcl GetObjResult (interp) ; 


This simply evaluates the string passed to it. If it’s successful, it returns 
rct_ox, and on failure, it returns rct error as well as setting a result in the 
interpreter. 

You can use the rc1_cetobjresuit function to retrieve a pointer to the Tcl object 
containing the result. The object’s reference count is not incremented; use 
Tcl_IncrRefCount to increment its reference count if you need to retain a long- 
term pointer to the object. For legacy code, tci_cetstringresuit returns the 
result as a string; you should use tc1_cetopjresuit for new code development. 


Note 


Because of the way Tcl works internally in versions prior to 8.4, it may 
need to make some temporary modifications to the string while it is 
working with it, so it is important that you pass a modifiable string to 
_eval rather than pass it a string constant directly. Code such as 
Tcl Eval(interp, "your script") may fail! 


Bb 


To 


If you want to guarantee maximum efficiency from your script, consider 
USING tcl _Evalopjex. In addition to using the object interface, Tcl also byte- 
compiles and caches the code passed to it, making it significantly faster 


662 


should it be executed again at some point in the future. 


Tcl Obj *script = Tcl_NewStringObj ( 
"while { $i < 10 } { .... }", -1); 

Tcl _IncrRefCount (script) ; 

Tcl EvalObjEx(interp, script, 0); 


This example creates a new string object that contains the script we wish to 
evaluate, increases its reference count, and then evaluates it. The o in the 
call to tci_evalopjzx 18 its “flags” argument. The two valid flags are 
rcL_EvaL_prrect, Which instructs Tcl not to byte-compile the script, and 
TCL_EvAL_cLopaL, Which ensures that the script is processed at the global level, 
running in the global namespace and using only global variables. 

Each call to a procedure such as rc1_#va1 must contain a complete script. The 
following does not work: 


char partl[] = "set "; 
char part2[] = "a "; 
char part3[] = "32"; 


Tcl Eval(interp, partl); /* Fails. */ 
Tcl_Eval(interp, part2); 


Tcl Eval(interp, part3); 


This code fails at the first call to 1c1_zvai, because the script it is attempting 
to evaluate is not complete. 


33.3 Dynamically Building Scripts 


There are several ways to compose a script from multiple pieces. The 
simplest is to build the command up as a list, in order to properly quote 
whitespace within individual elements: 


Tcl Obj *cmd; 
cmd = Tcl NewObj(); 
Tcl ListObjAppendElement (interp, cmd, 


Tcl NewStringObj("puts", -1)); 
Tcl _ListObjAppendElement ( 
interp, cmd, Tcl_NewStringObj ("hello world", -1)); 


Tcl IncrRefCount (cmd) ; 
Tcl EvalObjEx(interp, cmd, Q); 
Tcl DecrRefCount (cmd) ; 


Note that because we build the command up as a list, with 
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Tcl_ListObjAppendzlement, We don’t have to quote the helio worla string 
ourselves, even though it contains a space. When Tel evaluates the object, it 
is evaluating an object akin to puts {nello woria}. Using lists is also more 
efficient than using strings. If one of the elements is a number, for example, 
it can be added to the list as a number instead of the number’s string 
representation. 

Another way of dynamically creating a command to evaluate is by using the 
Tcl_Evalobjv function. It takes an array of Tcl objects and a count of the 
objects as arguments, in addition to an interpreter: 


int i = 0; 

Tcl Obj *scriptArr [3] ; 

scriptArr[0] = Tcl NewStringObj("set", -1); 
scriptArr[1] = Tcl_NewStringObj("a", -1); 
scriptArr[2] = Tcl_NewIntObj (32, -1); 

for (i = 0; i < 3; i++) { 


/* Increase the reference counts. */ 
Tcl _IncrRefCount (scriptArr [i] ); 


} 
Tcl EvalObjv(interp, scriptArr, 3, 0); 
for (i = 0; L-< 33 i++) { 
/* Decrease the reference counts. */ 
Tcl_DecrRefCount (scriptArr [i] ); 


In this code, we create the array of objects, fill it in, increment the reference 
counts, perform the evaluation, and then lower the reference counts again. 


33.4 Tcl Expressions 


In addition to evaluating Tcl code, you can also calculate the result of a Tcl 
expression. Expressions are useful as conditions for commands like is and 
while, OF aS a way to perform some math with Tcl variables. See Chapter 4 
on the expe command for further information on the syntax and utility of 
expressions. 

The basic method of performing an expression evaluation is via functions 
like Tcl_ExprTYPE and Tcl ExprTYPEObj, where ryez 1S one of Long, Double, OF Boolean, 
and the result is stored in a variable of the corresponding C type; for 
instance: 
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long result = 0; 

Tcl Obj *expr = Tcl NewStringObj("($foo / 2) + 1", -1); 
Tcl IncrRefCount (expr) ; 

Tcl_ExprLongObj(interp, expr, &result); 
Tcl_DecrRefCount (expr) ; 


This code creates a string object from the string (soo / 2) + 1, evaluates it, 
and stores the result in the result variable. 

If you don’t need the result returned as a particular C type, there are two 
generic functions for evaluating expressions: tc1_Expropj and tcl _Exprstring. 
The string form is the simplest, but it sacrifices some speed because the 
result is stored as a string. 


char *result = NULL; 

char *exprstr = "2 + 2"; 

Tcl ExprString(interp, exprstr) ; 
result = Tcl _GetStringResult (interp) ; 


This calculates 2 + 2 and evaluates to a string result of 4. You can then fetch 
the result with a call to Tcl GetStringResult. 
In the following we use the object-based call 1c1_Expronj3: 


Tcl Obj *result; 

Tcl_ Obj *expr = Tcl_NewStringObj("($foo / 2) + 1", -1); 
Tcl_IncrRefCount (expr) ; 

Tcl_ExprObj(interp, expr, &result); 

Tcl_ DecrRefCount (expr) ; 


Tcl DecrRefCount (result) ; 
/* You are responsible for lowering the reference count of the 
result. */ 


The object API is a bit more complex to use, but it is faster because it stores 
the result as a Tcl object with some type of numeric representation, rather 
than converting it back to a string. 
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34. Accessing Tcl Variables 


In this chapter we cover how to set Tcl variables from C, how to read their 
values, and how to delete them. We also describe how to link C variables 
and Tcl variables, so that when one changes, the other changes as well. Also 
included is a description of variable traces. 


34.1 Functions Presented in This Chapter 


This chapter covers the following functions for manipulating Tcl variables 
from C code: 


° Tcl Obj *Tcl_ SetVar2Ex(Tcl_Interp *interp, 


CONST char *namel, CONST char *name2, 
Tcl Obj *newValuePtr, int flags) 
Sets the variable given by name1 (and name2 1n the case of an array element) to 
newValuePtr. 
® CONST char *Tcl SetVar(Tcl Interp *interp, 
CONST char *varName, CONST char *newValue, 
int flags) 
Sets the variable varname tO newvalue. 
® CONST char *Tcl_ SetVar2(Tcl_Interp *interp, 


CONST char *namel, CONST char *name2, 


CONST char *newValue, int flags) 
Sets the variable given by name1 (and name2 in the case of an array element) to 
newValue. 
* Tcl Obj *Tcl_ ObjSetVar2 (Tcl Interp *interp, 


Tcl Obj *partiPtr, Tcl_Obj *part2Ptr, 


Tcl Obj *newValuePtr, int flags) 
Sets the variable given by Tcl objects partirer (and part2rtr 1n the case of an 
array element) to newvaiuertr. 


© Tcl Obj *Tcl_ GetVar2Ex(Tcl_Interp *interp, 


CONST char *namel, CONST char *name2, int flags) 
Retrieves the contents of the variables given by name1 and name2 as a Tcl 
object. 
® CONST char *Tcl GetVar(Tcl Interp *interp, 


CONST char *varName, int flags) 
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Retrieves the contents of the variable varvame as a string. 
® CONST char *Tcl GetVar2(Tcl_ Interp *interp, 
CONST char *namel, CONST char *name2, int flags) 
Retrieves the contents of the variables given by namez and name2 aS a String. 
* Tcl Obj *Tcl_ObjGetVar2 (Tcl Interp *interp, 
Tcl Obj *partiPtr, Tcl_Obj *part2Ptr, int flags) 
Retrieves the contents of the variables given by Tcl objects partirer and 
part2ptr aS a Tcl object. 
® int Tcl UnsetVar(Tcl Interp *interp, CONST char *varName, 
int flags) 
Unsets the variable varname. 
* int Tcl UnsetVar2(Tcl_ Interp *interp, CONST char *namel, 
CONST char *name2, int flags) 
Unsets the variables given by name1 and namez. 
® int Tcl _TraceVar(Tcl_Interp *interp, 
CONST char *varName, int flags, 
Tcl VarTraceProc proc, ClientData clientData) 
Arranges to call the function proc when the trace on varvame matches one of 
the conditions specified in fiags. 
® Tcl UntraceVar (Tcl Interp *interp, 
CONST char *varName, int flags, 
Tcl VarTraceProc proc, ClientData clientData) 
Unsets a trace. Arguments must match those used to set the trace. 


® ClientData clientData Tcl VarTraceInfo(Tcl_ Interp *interp, 


CONST char *varName, int flags, 


Tcl VarTraceProc proc, ClientData prevClientData) 


Returns the ciientpata for a previously set trace. 
® int Tcl TraceVar2 (Tcl Interp *interp, 
CONST char *namel, CONST char *name2, int flags, 


Tcl VarTraceProc proc, ClientData clientData) 


Tcl UntraceVar2(Tcl_Interp *interp, 
CONST char *namel, CONST char *name2, int flags, 


Tcl VarTraceProc proc, ClientData clientData) 


ClientData Tcl VarTraceInfo2(Tcl_Interp *interp, 
CONST char *namel, CONST char *name2, int flags, 
Tcl VarTraceProc proc, ClientData prevClientData) 
These functions are the same as the previous three, but instead of taking one 
variable name as an argument, they take a name1 and name2, where name2 18 used 
to refer to array elements. 
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34.2 Setting Variable Values 


Tel variables differ from Tcl objects in that an object is just some value that 
can be used by Tcl, whereas a variable is an object that is accessible at the 
script level via a variable name. 

The simplest way to create a Tcl variable is with the rci_setvar command: 


Tcl SetVar(interp, "foo", "42", 0); 


’ ® 4 
/* Sets the value of the foo variable to "42", */ 


Both the variable name and its value are given as strings, meaning that this 
is not an efficient way to create variables with numeric values. If speed is 
not an issue, this is the easiest way to get the job done. The variable can be 
either a normal variable or an array element—such as foo OF foo (bar). Other 
than this, it is not parsed at all, and no substitutions occur. You could use the 
string tsa} as the variable name if you so chose, although you should not use 
names like this because they make your code confusing and difficult to read. 
The object-based version of this command is as follows: 


Tel_Obj *intObj; 
intObj = Tcl NewIntObj (42); 

Tcl _IncrRefCount (intObj) ; 

Tcl SetVar2Ex(interp, "foo", NULL, intObj, 0); 
Tcl DecrRefCount (intObj) ; 


When this code snippet is executed, it creates a foo variable, as before. The 
difference is that its value is an object containing the number 42, which is 
more efficient to work with if the commands that subsequently operate on foo 
deal with numbers. 

The tci_setvar2ex function also lets us create array elements by using both the 
second and third arguments, like so: 


Tcl SetVar2Ex(interp, "foo", "bar", intObj, 0); 


This creates the foo (bar) array element. 
The last argument to most variable functions—the o in the preceding 
examples—is an ORed combination of flag bits: 

® TCL GLOBAL ONLY 
Looks up the variable in the global namespace only, even if execution is 
deep within nested procedures. 


® TCL NAMESPACE ONLY 
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Looks up the variable in the current namespace only. 

* TCL LEAVE ERR MSG 
Sets the interpreter’s result to an error if a problem occurs when creating 
the variable. Otherwise, most of the set commands simply return a nox 
value. This may prove useful within commands that should fail if they are 
not able to set the variable in question. 

® TCL APPEND VALUE 
Instead of replacing an existing value of this variable, appends to it. If the 
variable does not exist, 1t is created as normal. 

° TCL LIST ELEMENT 
The new value for the variable is converted to a list element (quoted, if 
necessary). Depending on whether the rct_appenp_vatue flag is set, the variable 
is either set to a list containing this element, or the element is appended to 
the value contained in the variable. 
In addition to the tc1_setvar and tc1_setvar2zx functions just described, the Tcl 
API provides 1c1_opjsetvar2, which takes Tcl objects for the variable name 
and/or array element name. For example, to create a list of numbers: 


int i = 0; 
Tcl Obj *intObj; 
for (i = 1; 1 <= 10; i++) { 
intObj = Tcl NewIntObj (i); 
Tcl IncrRefCount (intObj) ; 
Tcl SetVar2Ex(interp, "numlist", NULL, intObj, 
TCL LIST_ELEMENT | TCL APPEND VALUE}; 
Tcl DecrRefCount (intObj) ; 


In Tcl, printing the numiist variable would result in 


puts $numilist 
> 12345678910 


34.3 Reading Variables 


The “read” that corresponds to the 1ci_setvar “write” 18 1c1_Getvar! 


char *value; 
value = Tcl _GetVar(interp, "foo", 0); 
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This returns a string pointer with the value contained in the variable foo. The 
string returned belongs to Tcl, so if you wish to keep it or modify it, make a 
copy with straup. Calling rc1_setvar OF tcl_setvar2 for the variable invalidates 
the pointer, so copy it immediately if you want to save it. 

The flags for the various cetvar operations are ‘ct _ciopa.onty and 
TCL_LEAVE_ERR Msc, Which have the same meaning as for the setvar functions. 

The object-based cetvar function 18 tc1_cetvarzex, which returns a Tcl object: 


Tcl Obj *value; 
value = Tcl_GetVar2Ex(interp, "foo", NULL, 0); 


With a vc1_ op} in hand, you could use 1c1_cetintFromon; to get the integer value 
and then manipulate it, which is much more efficient than parsing the string 
a2 to obtain its integer value: 


int intval = 0; 
if (Tcl_GetIntFromObj(interp, value, &intval) != TCL OK) { 
return TCL ERROR; 


intval = intval * 42; 
34.4 Unsetting Variables 


It is possible to remove a variable using the tc1 unsetvar OF tcl_Unsetvar2 
commands. Either 


Tcl_UnsetVar(interp, "foo(bar)", 0); 
or 
Tcl_UnsetVar2(interp, "foo", "bar", 0); 


removes the bar element from the foo array. These functions have the same 
effect as the Tcl unset command. The Tcl equivalent to this code is 


unset foo(bar) 


These functions return tct ox on success and rct eRRor If the variable doesn’t 
exist or can’t be removed for some other reason. The rc ctosar_onty and 
TCL _LEAVE_ERR Msc flags may be used with these calls. If an array name 1s given, 
and no element is specified, the entire array 1s removed. 
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34.5 Linking Tel and C Variables 


Tcl provides a mechanism called variable linking that allows you to 
associate a Tcl variable with a C variable. Whenever the Tcl variable is 
read, the value is supplied from the C variable, and whenever the Tcl value 
is written, the new value is stored in the C variable as well. The function 
Tcl_Linkvar Creates a link. Consider the following C code: 


int value = 32; 
Tcl_LinkVar (interp, "x", (void *) &value, TCL _LINK_INT) ; 


This links the Tcl variable « to the C variable value. Whenever the Tcl 
variable x is read, Tcl converts vaiue to a decimal string and returns the 
string as the value of x (s2 in the example). If vaiue is modified, the new 
value is returned the next time the Tcl variable « is read. Whenever the Tcl 
variable x 1s written, x’s new value is converted from a Tcl object to an 
integer and stored in vaiue. Ifa Tcl script attempts to write a value into « that 
isn’t a proper integer, the write is rejected with an error: 


set x "oops!" 


=> can't set "x": variable must have integer value 

The last argument to tc1_tinkvar indicates the type of the C variable. In the 
previous example, the type is rtcz tx int, which indicates that the C 
variable is an integer and only proper integer values may be stored in the 
Tel variable. Table 34.1 lists the allowed values for the type argument and 
the C type to which they correspond. For any of the numerical types 
supported by rci_ninkvar, any attempt to assign a value to the Tcl variable that 
cannot be converted to the specified type (for example, a non-numerical 
value or an out-of-range value) is rejected with a Tcl error. 


Table 34.1 Allowed Type Arguments for 1c1_Linkvar 
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Type flag C type 
TCL_LINK_INT int 
TCL_LINK_UINT unsigned int 
TCL LINK CHAR char 

TCL LINK _UCHAR unsigned char 
TCL LINK SHORT short 

TCL LINK _USHORT unsigned short 
TCL_LINK_LONG long 
TCL_LINK_ULONG unsigned long 
TCL LINK DOUBLE double 

TCL LINK FLOAT float 

TCL LINK WIDE INT Tcl WideInt 
TCL LINK WIDE _UINT Tel WideUInt 
TCL_LINK_BOOLEAN int 

TCL LINK STRING char * 


For the tc._tix strive type, if the C variable’s value is not nux1, 1t must point 
to a string allocated with ci aiioc OF ckalloc. When the Tcl variable is 
modified, the old string is freed and a new one is allocated to hold the 
variable’s new value. The Tcl variable may be assigned any string value. 
The Tcl variable returns the string nuit if it is read and the C variable is wuz1. 


Note 


Only C variables allocated globally or dynamically, rather than those 
from the stack, should be linked. 


For example, to link to a string, you would do this: 


char *foo = "Hello, 


/* Note the pointer 


Tcl LinkVar(interp, 


The flag TCL_LINK_RI 


EAD ONLY 


following example: 


World"; 
to the pointer. */ 
"hi", (void *) &f00, TCL LINK STRING); 


may also be ORed with the type, as in the 


Tel_LinkVar(interp, "x", (void *), & value, 
TCL_LINK INT|TCL_LINK READ ONLY); 
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This makes the Tcl variable read-only: any attempt to modify the variable 
from Tcl is rejected with an error. 

While the Tcl variable is linked, if it is unset, Tcl automatically re-creates 
the variable. The Tcl variable cannot be unset permanently until the link is 
removed. The function tci_uniinkvar removes a variable link previously 
established by rci_tinkvar. For example, the following statement removes the 
link created previously: 


Tel_UnlinkVar(interp, "x"); 


34.6 Setting and Unsetting Variable Traces 


Variable traces allow you to specify a C function to be called whenever a 
variable is read, written, or unset. Traces can be used for many purposes. In 
Tk, for instance, you can configure a button widget so that it displays the 
value of a variable and updates itself automatically when the variable is 
modified. This feature is implemented with variable traces. You can also 
use traces for debugging, to create read-only variables, and for many other 
purposes. 


Note 


Although they are quite powerful, you should be careful in your use of 
traces, because they make it easy to create “magic variables” that, to 
the user, appear to behave very strangely. 


The tci tracevar and tci tracevar2 calls create variable traces, as in the 
following example: 


Tcl_TraceVar(interp, "x", TCL_TRACE WRITES, 
WriteProc, (ClientData)NULL); 


This creates a write trace on variable « in interp, Which means that writeProc 
is invoked whenever « is modified. The third argument to tc1_tracevar 18 an 
ORed combination of flag bits that select the operations to trace: 
TCL TRACE READS for reads, TCL TRACE WRITES for writes, and TCL _TRACE_UNSETS for 
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unsets. In addition, the flag rc. ciozaz ony may be specified to force the 
variable name to be interpreted as global. tc1 tracevar and tc1_tracevar2 
normally return rct_ox. If an error occurs, they set an error result in the 
interpreter and return rc1_eRRor. 

The library functions tc1 untracevar and tcl untracevar2 remove variable 
traces. For example, the following call removes the trace set previously: 


Tcl_Untrace(interp, "x", TCL_TRACE_ WRITES, 
WriteProc,(ClentData)NULL); 


Tcl_Untracevar finds the specified variable; looks for a trace that matches the 
flags, trace function, and ciientpata specified by its arguments; and removes 
the trace if it exists. If no matching trace exists, tc1_untracevar does nothing. 
Tcl_Untracevar and tc1_untracevar2 accept the same flags as tc1_tracevar. 


34.7 Trace Callbacks 


Trace callback functions such as writeproc 1n the previous section must match 
the following prototype: 
typedef char *Tcl_ VarTraceProc ( 
ClientData clientData, Tcl_Interp *interp, 
} 


char *namel, char *name2, int flags); 


The ciientpata and interp arguments are the same as the corresponding 
arguments passed tO tc1_tracevar OF Tcl_TraceVar2. clientData typically points to 
a structure containing information needed by the trace callback. name: and 
name2 give the name of the variable in the same form as the arguments to 
Tel Setvar2. flags consist of an ORed combination of bits. Either 
TCL TRACE READS, TCL TRACE WRITES, OL TCL TRACE uNsETs 18 Set to indicate which 
operation triggered the trace, and rcz ciozar onty 18 Set if the variable is a 
global variable that isn’t accessible from the current execution context; the 
trace callback must pass this flag back into functions like tc1 cetvar2 if it 
wishes to access the variable. The bits cct rrace pesrroven and 
TCL INTERP DESTROYED are Set in special circumstances, as described in Section 
34.10. 

For read traces the callback is invoked just before the tc1 cetvar or other 
variable read operations return the variable’s value; if the callback modifies 
the value of the variable, the modified value is returned. For write traces the 
callback is invoked after the variable’s value has been changed. The 
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callback can modify the variable to override the change, and this modified 
value is returned as the result of rc1 setvar or other variable write functions. 
For unset traces the callback is invoked after the variable has been unset, so 
the callback cannot access the variable. Unset callbacks can occur when a 
variable has been unset, when a Tcl procedure returns (thereby deleting all 
of its local variables), or when an interpreter is destroyed (thereby deleting 
all of the variables in the interpreter). 

A trace callback function can invoke ci cetvar and tci setvar or their 
equivalents to read and write the value of the traced variable. All traces on 
the variable are temporarily disabled while the callback executes, so calls 
tO tcl_Getvar, Tcl_setvar, and the like do not trigger additional trace callbacks. 
As mentioned earlier, unset traces aren’t invoked until after the variable has 
been deleted, so attempts to read the variable during unset callbacks fail. 
However, it is possible for an unset callback function to write to the 
variable, in which case a new variable is created. 

This code sets a write trace that prints out the value of variable « each time 
itis modified: 


Tcl_TraceVar(interp, "x", TCL TRACE WRITES, Print, 
(ClientData) NULL) ; 


char *Print(ClientData clientData, Tcl _Interp *interp, 
char *namel, char *name2, int flags) { 
char *value; 
value = Tcl _ GetVar2(interp, namel, name2, 
flags & TCL GLOBAL ONLY); 
if (value != NULL) { 
if (mame2 == NULL) { 
printf ("new value of %s is %¢s\n", 
namel, value}; 
} else { 
printf ("new value of %*s(%s) is #s\n", 
namel, name2, value}; 
} 


return NULL; 


} 


print Must pass the rc1 ctosar_onty bit of its f1ags argument to 1c1 cetvar2 IN 
order to make sure that the variable can be accessed properly. tc1_cetvar2 
should never return an error, but print checks for one anyway and doesn’t try 
to print the variable’s value if an error occurs. In this example we don’t use 
the tci_opj variant of tci_cetvar, because tc1 cetvar2 18 simpler and more 
direct. 
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Trace callbacks normally return wor1 values; a non-null value signals an 
error. In this case the return value must be a pointer to a static string 
containing an error message. The traced access aborts, and the error 
message is returned to whoever initiated that access. For example, if the 
access was invoked by a set command or s substitution, a Tcl error results; 
if the access was invoked via tc1_ cetvar, it returns nuzt and also sets an error 
result in the interpreter if the tc. tzave_err usc flag was specified. 

The following code uses a trace to make the variable zip read-only with the 
value 94114: 


Tcl Obj *numobj = Tcl_NewIntoObj (94114) ; 

Tcl IncrRefCount (numobj) ; 

Tel TraceVar(interp, "zip", TCL_TRACE WRITES, Reject, 
(ClientData)numob3) ; 


char *Reject(ClientData clientData, Tcl _Interp *interp, 
char *namel, char *name2, int flags) { 
Tel Obj *correct = (Tcl_Obj *) clientData; 
Tcl SetVar2Ex(interp, namel, name2, 
correct, flags & TCL GLOBAL ONLY); 
return “variable is read-only"; 


—) 


The reject function is a trace callback that is invoked whenever zip is written 
to. It returns an error message to abort the write access. Since zip has 
already been modified before reject 18 invoked, reject must undo the write by 
restoring the variable’s correct value. The correct value is passed to the 
trace callback using its ciientpata argument. This implementation allows the 
same function to be used as the write callback for many different read-only 
variables; a different correct value can be passed to reject for each variable. 


34.8 Whole-Array Traces 


You can create a trace on an entire array by specifying an array name to 
Tel_Tracevar OF Tcl Tracevar2 Without an element name. This creates a whole- 
array trace: the callback function is invoked whenever any of the specified 
operations is invoked on any element of the array. If the entire array 1s unset, 
the callback is invoked just once, with name1 containing the array name and 
name2 being NULL. 


34.9 Multiple Traces 
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Multiple traces can exist for the same variable. When this happens, each of 
the relevant callbacks is invoked on each variable access. The callbacks are 
invoked in order from the one most recently created to the oldest. If there 
are both whole-array traces and individual element traces, the whole-array 
callbacks are invoked before element callbacks. If an error is returned by 
one of the callbacks, no subsequent callbacks are invoked. 


34.10 Unset Callbacks 


Unset callbacks are different from read and write callbacks in several ways. 
First of all, unset callbacks cannot return an error condition; they must 
always succeed. Second, two extra flags are defined for unset callbacks: 
TCL TRACE DESTROYED ANd rc. intERP pesTRoveD. When a variable is unset, all of its 
traces are deleted; unset traces on the variable are still invoked, but they are 
passed the rct track _vestroven flag to indicate that the trace has now been 
deleted and won’t be invoked anymore. If an array element is unset and 
there is a whole-array unset trace for the element’s array, the unset trace is 
not deleted and the callback is invoked without the tct_tracz_pestroven flag 
being set. 

If the ct trerp_pestrovep flag is set during an unset callback, it means that the 
interpreter containing the variable has been destroyed. In this case the 
callback must be careful not to use the interpreter at all, since the 
interpreter’s state 1s in the process of being deleted. The callback should 
merely clean up its own internal data structures. 
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35. Creating New Tcl Commands 


For everyone planning on interacting with Tcl’s C API, whether through 
extensions to Tcl or by embedding Tcl, creating new Tcl commands is the 
primary means of integrating Tcl with your library or application. 

Each Tcl command is implemented by a function written in C. When a Tel 
command is invoked during script evaluation, Tcl calls this function to carry 
out the command. This chapter describes how to write command functions, 
how to register them in an interpreter, and how to manage the result of the 
command. 


35.1 Functions Presented in This Chapter 


* Tcl Command Tcl _CreateObjCommand (Tcl Interp *interp, 
CONST char *cmdName, Tcl_ObjCmdProc proc, 


ClientData clientData, 


Tcl_CmdDeleteProc deleteProc) 
Creates a new command that is visible in Tcl as cmaname, Which, when called, 
runs the function proc. 
*® Tcl WrongNumArgs (Tcl Interp *interp, int objc, 
CONST Tcl Obj *objv[], CONST char *message) 
Generates a standard error message and stores it in the result object of 
interp. The message includes the opjc initial elements of onjv plus message. 
* int Tcl DeleteCommand (Tcl Interp *interp, 
CONST char *cmdName) 
Deletes the command cmawame. 
* int Tcl DeleteCommandFromToken(Tcl_Interp *interp, 
Tcl Command token) 
Deletes the command referred to by toxen. 
* Tcl SetObjResult (Tcl _Interp *interp, Tcl Obj *objPtr) 
Sets opjrer as the result for interp and increments its reference count. This 
replaces any existing result and decrements the reference count for any old 
result object. 


* Tcl SetResult (Tcl_Interp *interp, char *result, 


Tcl_FreeProc *freeProc) 


Arranges for resuic to be the result for the current Tcl command in interp, 
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replacing any existing result. The rreerroc argument specifies how to manage 
the storage for the result argument. 
® Tcl AppendResult (Tcl _Interp *interp, char *result, 
char *result, ... , (char *) NULL) 
Tcl AppendResultVA(Tcl_Interp *interp, va_list argList) 

Takes each of its resuit arguments and appends them in order to the current 
result associated with interp. tcl _appendresuitva 18 the Same aS 1c1 appendResult 
except that instead of taking a variable number of arguments, it takes an 
argument list. 


* Tcl AppendElement (Tcl Interp *interp, char *element) 
Takes only a single cement argument and appends that argument to the current 
result as a proper Tel list element. 
* Tcl ResetResult (Tcl _Interp *interp) 
Clears the result for intero and leaves the result in its normal empty 
initialized state. If the result is an object, its reference count is decremented. 
® int Tcl _GetCommandInfo(Tcl_Interp *interp, 
CONST char *cmdName, Tcl CmdInfo infoPtr) 
Obtains information about the command cmavame and places it in inforer. 
® int Tcl SetCommandInfo(Tcl_Interp *interp, 
CONST char *cmdName, Tcl CmdInfo infoPtr) 
Modifies functions and client data associated with the command cmaname. 
* int Tcl_GetCommandInfoFromToken (Tcl Command token, 
Tcl _CmdInfo infoPtr) 
Obtains information about the command referred to by toxen and places it in 
infoPtr. 
* int Tcl SetCommandInfoFromToken (Tcl Command token, 
Tcl_CmdInfo infoPtr) 
Modifies functions and client data associated with the command referred to 
by token. 
® CONST char *Tcl_GetCommandName (Tcl Interp *interp, 


Tcl Command token) 


Gets the name of the command referred to by toxen. 

* void Tcl _GetCommandFullName(Tcl_ Interp *interp, 

Tcl Command token, Tcl Obj *objPtr) 

Produces the fully qualified name of a command from token. The name, 
including all namespace prefixes, is appended to the object specified by 
obj Ptr. 

* Tcl Command Tcl GetCommandFromObj (Tcl Interp *interp, 

Tcl Obj *objPtr) 

Returns a token for the command specified by the name in a 1c1 on}. The 
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command name is resolved relative to the current namespace. Returns nox if 
the command is not found. 
® Tcl Trace Tcl CreateObjTrace (Tcl Interp *interp, 

int level, int flags, Tcl _CmdObjTraceProc objProc, 

ClientData clientData 

Tcl _CmdObjTraceDeleteProc deleteProc) 
Creates a trace. The onjrroc function is called prior to the execution of every 
command in interpreter interp. Only commands at or below nesting level 
level are traced. Returns a trace that can be passed to 1c1_peietetrace. 


* Tcl Trace Tcl CreateTrace(Tcl_ Interp *interp, 
int level, Tcl CmdTraceProc func, 
ClientData clientData) 
Similar to tc1_createobjtrace, but for command functions implemented using 
the older interface. 
® Tcl DeleteTrace(Tcl_Interp *interp, Tcl Trace trace) 


Deletes a trace. 


35.2 Command Functions 


The interface to an object-based command function is defined by the 
Tcl_cmaProc function prototype: 


typedef int Tcl_ObjCmdProc | 
ClientData clientData, Tcl_Interp *interp, 
int objc, Tcl Obj *CONST objv[]); 


In other words, functions that implement new Tcl commands have this 
signature. This replaces the older-style string-based commands, which have 
the following function signature—included here only to aid in the 
understanding of old code that is in need of updating: 


typedef int Tcl_CmdProc( 
ClientData clientData, Tcl_Interp *interp, 
int argc, char *argv[]); 


A command function is invoked when its corresponding Tcl command is 
executed, and it is passed four arguments. The first, clientpata, 18 discussed 
in Section 35.7. The second, interp, is the interpreter in which the command 
was executed. The third and fourth arguments are similar in meaning to the 
argc and argv arguments to a C main program: onjc specifies the total number of 
arguments (words) to the Tcl command, and ovjv is an array of pointers to 
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the tc1 op; values of the words. Tcl processes all the special characters such 
as s and ,; before invoking command functions, so the values in opjv are 
those left after any substitutions have been performed. 

The name of the command is counted in onjc (meaning the command cma foo 
has an ovjc of 2) and is included as the first element of objv. objviopjc] 18 nutty. 
A command function “returns” two values, just like rc1_svai and tc1_zvairile. 
The C function returns an integer completion code such as tc1_ox OF tTcL_ERROR 
and additionally sets a result in the Tcl interpreter with rc1_setopjresuit. The 
Tcl _WrongNumargs Call is also commonly used to indicate an error condition 
caused by an incorrect number of arguments to the Tcl command. 

Here is the command function for a new command called eq that compares 
its two arguments for string equality: 


static int 
EgCmd(ClientData clientData, Tcl_Interp *interp, 
int objc, Tcl_Obj *CONST objv[]) { 
char *argl; 
char *arg2; 
Tcl Obj *result; 
if (objc != 3) { 
Tcl WrongNumArgs(interp, 1, objv, "stringl string2"); 
return TCL ERROR; 


} 


argl = Tcl_GetString(objv[1]); 
arg2 = Tcl.Gets emis PORTE th 
if (stremp(argl, arg2) == 0) 
result = Tcl_NewBooleanObj (1 
} else { 
result = Tcl _NewBooleanObj (0} ; 
1 
f 


Tcl SetObjResult(interp, result); 
return TCL OK; 


} 


zqcma Checks to see that it was called with exactly two arguments (1.e., the 
objc has a value of 3, which includes the command name), and if not, it uses 
Tcl WrongNumArgs to Set an error result and then returns tcz error. Otherwise, it 
fetches the string values of its two arguments, compares them, and creates a 
Boolean object that indicates whether they are indeed equal or not. It then 
returns rct_ox to indicate that the command completed normally. zqcma does 
not use its clientdata argument, but this argument plays an important role in 
many other Tcl commands, as you will see shortly. 


Note 
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This command does not check the equivalence of two objects, only 
their string equality. Consider two numbers, 1 and 1.0—zqcma will 
indicate that they are different. 


A command function should treat the contents of the ovjv array as read-only. 
In general, it is not safe for a command function to modify these objects. 


35.3 Registering Commands 


In order for a command function to be invoked by Tcl, you must register it 
by calling Tcl _CreateObjCommand, which takes the form 
Tcl Command token Tcl_CreateObjCommand ( 
Tcl Interp *interp, char *commandName, 
Tcl ObjCmdProc *proc, ClientData clientData, 
Tcl CmdDeleteProc deleteProc) ; 


This is the “magic” that associates the string in Tcl with the C function that 
implements it. Here is the simple program from Section 31.3, augmented 
with a call to Tcl CreateObjCommand: 
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#include <stdio.h> 
#include <tcl.h> 


int main(int argc, char *argv[]) { 
Tcl _Interp *interp; 
char *result; 
int code; 


if (arge != 2) { 
fprintf(stderr, "Wrong # arguments: "); 
fprintf(stderr, "should be \"%s fileName\"\n", 
argv [0] )}; 
exit (1); 


} 


interp = Tcl_CreateInterp(); 
Tcl CreateObjCommand(interp, "eq", EqCmd, 
(ClientData) NULL, 
(Tcl _CmdDeleteProc *) NULL); 
code = Tcl EvalFile(interp, argv[1]); 
result = Tcl _GetStringResult (interp) ; 


if (code != TCL_OK) { 
printf ("Error was: s\n", result); 
exit (1); 


printf ("Result was: %s\n", result); 
exit (0); 


} 


The first argument to tc1_createobjcommana Identifies the interpreter in which 
the command will be used. The second argument specifies the name for the 
command, and the third argument specifies its command function. The fourth 
and fifth arguments are discussed in Section 35.7; they can be specified as 
nuit for simple commands like this one. 1c1_createoojcommana Creates a new 
command for interp named eq. If a command by that name already exists, it is 
silently deleted. Whenever ec is invoked in interp, Tel calls eqcma to carry out 
its function. The tc1i createobjcommana function returns a rc1 commana “token” that 
can be used to further manipulate and obtain information about the 
command. See Section 35.8 and Section 35.9 for further information. 

If the code for eqcma 18 included in the same file with the main function, it can 
be compiled and invoked just like the simple program in Section 31.3. 
Alternatively, zgcma could be compiled into an extension and loaded, as 
described in Chapter 36. In either case, scripts are now able to use the new 
eq Command: 
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eq abc def 


— © 


eq i 4 
=k 
set w .dlg 
set w2 .dlg.ok 
eq $w.ok S$w2 
= 1 


When processing scripts, Tcl carries out all of the command-line 
substitutions before calling the command function, so when zqcma is called 
for the last eg command in the preceding code, both opjviij_ and opjvi2) 
contain objects with the string .a1g.ox. 

Tel _CreateObjCommana 18 usually called by applications during initialization to 
register application-specific commands, but new commands can be created 
at any time while an application is running—even by other commands. For 
example, the proc command creates a new command for each Tcl procedure 
that is defined, and Tk creates a widget command for each new widget. In 
Section 35.7 and Section 35.9 you will see examples where the command 
function for one command creates a new command. 

Commands created by tci_createonjcommana are indistinguishable from Tcl’s 
built-in commands. Each built-in command has a command function with the 
same form as zqcma, and you can redefine a built-in command by calling 
Tcl CreateObjCommana WIth the name of the command and a new command 
function. 


35.4 The Result Protocol 


The sqcma function returns a result through a call to the 1c1 setobjresuit 
function. This is the most efficient way to set a result. In the example in the 
previous section, for instance, we create the type as a Boolean, so that if the 
eq command’s result is read by another command that expects a Boolean as 
an argument, no translation is necessary. If we were to provide a string 
result, it would have to be created, then parsed back into a Boolean (an 
integer). 

By setting an object as the result in the interpreter, Tcl automatically 
increments its reference count, so it’s not necessary for you to do it 
explicitly. 


3 5 e 5 Tcl_AppendResult 
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Another method of managing the result that is still useful, and reasonably 
current (it is used in Tcl internally), is 1c1_appendresuit, Which makes it easy 
to build up results in pieces. It takes any number of strings as arguments and 
appends them to the interpreter’s result in order. As the result grows in 
length, tc1_appenaresuit allocates new memory for it. tc1 appenaresuit May be 
called repeatedly to build up long results incrementally, and it does this 
efficiently, even if the result becomes very large (it allocates extra memory 
so that it doesn’t have to copy the existing result into a larger area on each 
call). Here is an example from Tcl’s source that sets an error message when 
it cannot open a file: 


i) 


Tcl AppendResult(interp, "couldn't read fil 
filename, "\": ", 
Tcl PosixError(interp), 
(char *) NULL); 

return TCL ERROR; 


The wuz argument in 1c1_appendresuit marks the end of the strings to append. 
Tcl _AppendElement 18 Similar tO 1c1_appendResult except that it adds only one 
string to the result at a time, and it appends it as a list element instead of a 
raw string. In modern Tel applications, it is probably best to construct a list 
as an object and provide that as an argument to tc1_setobjresult. 

If you set the result for an interpreter and then decide that you want to 
discard it (for example, an error has occurred and you want to replace the 
current result with an error message), you should call the function 
Tcl_ResetResult. It frees the current result and restores the interpreter’s result 
to its initialized state. You can then store a new value in the result in any of 
the usual ways. You need not call tc1_resetresuit If youre going to use 
Tel SetObjResult OF Tcl SsetResult to store the new result, because these 
functions take care of freeing any existing result. 


35.6 Tcl_SetResult and interp->result 


Before the advent of Tcl objects, the tc1_setresuit function was used, and in 
even older versions it was possible to set the result by manipulating fields 
of the interpreter structure directly. 


Note 
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This is slow and error-prone, and may not be supported in future Tcl 
releases, as it has been deprecated for years. We describe it here to 
assist the reader who is dealing with older code—and, we hope, 
updating it. 


The full definition of the tci interp structure, as visible outside the Tcl 
library, is 


typedef struct Tcl_Interp { 
char *result; 
Tcl FreeProc *freeProc; 
int errorLine; 

} Tcl _Interp; 


The first field, resuit, points to the interpreter’s current result. It is possible 
to set it directly to a string, by doing, for instance, 


interp->result = "Maximum temperature exceeded!"; 


Tcl also provides, by default, a small amount of storage space that can be 
written to directly. The exact quantity is defined by tc1_resutt_stzz, which is 
guaranteed to be at least 200. You may see this used for numeric results in 
code like the following: 


sprintf(interp->result, "%d", argc); 


It is also possible to allocate memory (Via maiicc or the like) and assign it to 
interp->result. It is at this point that the second field in the interp structure, 
freeProc, Comes into play. If the result is set from dynamically allocated 
memory, freeProc 18 a function that can free the memory when it is no longer 
used. A freeproc must be defined with this signature: 


typedef void Tcl FreeProc(char *block Ptr); 


The function 1s invoked with a single argument containing the address stored 
IN interp->result. In older code, maiioc 18 used for dynamic allocation—as 
opposed to ckalloc OF Tcl alloc, Which should always be used in new code. 
Thus, interp->freeproc 18 usually set to the sree function. 

Tcl _SetResult 18 a Step up from managing interp->resuit directly, yet it still 
requires a function to free memory once it is no longer in use. The first 
argument to tc1_setResult 1S an interpreter, the second argument is a string to 
use as the result, and the third argument gives additional information about 
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the string. rc_srartc means that the string is static, SO tc1_setresuit Just stores 
its address into interp->resuit. A value of rct_votarite for the third argument 
means that the string is about to change (for example, it is stored in the 
function’s stack frame), so a copy must be made for the result. 1c1_setresuit 
copies the string into the pre-allocated space if it fits; otherwise, it allocates 
new memory to use for the result and copies the string there (setting interp- 
>freeProc appropriately). If the third argument is tct_pywamtc, 1t means that the 
string was allocated with maiioc and should become the property of Tcl: 
Tol_SetResult S€tS interp->freeProc tO free aS described earlier. Finally, the third 
argument may be the address of a function suitable for use in interp->freeProc} 
in this case the string is dynamically allocated and Tcl eventually calls the 
specified function to free it. 


Note 


Once again: don’t use either of these approaches for any new code you 
develop. If you come across them in existing code, take a few minutes 
to bring the code up to date. 


35.7 ciientpata and Deletion Callbacks 


The fourth and fifth arguments to tc1_createobjcommana, clientData aNd deleteProc, 
were not discussed in Section 35.3, but they are useful when commands are 
associated with “objects” (not rc1_o»js, but objects as described in Section 
30.3). The ciientpata argument is used to pass a one-word value to a 
command function (typically the address of the C data structure for an 
object). Tcl saves the ciientpata value and uses it as the first argument to the 
command function. The type ciientpata 18 large enough to hold either an 
integer or a pointer value. 

clientbata Values are used in conjunction with callback functions. A callback 
is a function whose address is passed to a Tcl library function and saved in 
a Tcl data structure. Later, at some significant time, the address is used to 
invoke the function (“call it back’). A command function is an example of a 
callback: Tcl associates the function’s address with a Tcl command name 
and calls the function whenever the command 1s invoked. When a callback 
is specified in Tcl or Tk, a ciientpata argument is provided along with the 
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function’s address, and the ciientpata value is passed to the callback as its 
first argument. 


The ceieterroc argument to 1c1_createobjcommana Specifies a deletion callback. If 
its value isn’t nut, it is the address of a function for Tcl to call when the 
command is deleted. The function must match the following prototype: 


typedef void Tcl_ CmdDeleteProc(ClientData clientData); 


The deletion callback takes a single argument, which is the ciientpata value 
specified when the command was created. Deletion callbacks are used for 
purposes such as freeing the object associated with a command. 


static int 
ObjectCmd(ClientData clientData, 
Tel Interp *interp, int objec, 
Tcl Obj *CONST objv[]) { 
Counter *counterPtr = (Counter *)clientData; 
char *subcmd; 
if (objec != 2) { 
Tcl _WrongNumArgs(interp, 1, objv, 
"get | next"); 


return TCL ERROR; 
} 
subcmd = Tcl _GetString(objv[i]); 
if (stremp(subemd, "get") == 0) { 
Tcl SetObjResult (interp, 
Tcl NewIntObj (counterPtr-svalue} }); 


} else if (stremp(subemd, "next") == 0) { 
counterPtr->value ++; 

} else { 
Tcl Obj *result = Tcl_NewStringObj("", 0); 


Tcl AppendStringsToObj (result, 
"bad counter command\"", 
Tcl _GetString(objv[1]), 
"\": should be get or next", 
(char *})NULL); 
Tcl SetObjResult(interp, result); 
return TCL ERROR; 
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} 


return TCL OK; 


} 


static int 
CounterCmd(ClientData clientData, Tcl_Interp *interp, 
int objc, Tcl_Obj *CONST objv{[]) { 
Counter *counterPtr; 
Tcl_Obj *countername; 
Static int id = 0; 
if (objec != 1) { 
Tel WrongNumArgs(interp, 1, objv, NULL); 
return TCL ERROR; 


} 


counterPtr = (Counter *)Tcl_Alloc( 
sizeof (Counter) } ; 
counterPtr->value = 0; 
countername = Tcl NewStringObj("ctr", -1); 
Tcl AppendObjToOb] (countername, 
Tcl NewIntObj(id)}); 
id ++; 
Tcl CreateObjCommand(interp, 
Tcl_GetString({countername) , 
ObjectCmd, 
(ClientData}) counterPtr, 
DeleteCounter) ; 
Tcl _ SetObjResult(interp, countername} ; 
return TCL OK; 


} 


These functions demonstrate how ciientpata and aeleteproc can be used to 
implement counter objects. countercma creates new counters, which are 
implemented by the o»jectcma code. The application containing this code must 
register countercma aS a Tcl command using the following call: 


Tcl _CreateObjCommand(interp, "counter", CounterCmd,, 
(ClientData) NULL, 
(Tcl_CmdDeleteProc *) NULL); 


New counters can then be created by invoking the counter Tel command; each 
invocation creates a new object and returns a name for that object: 
counter 
=> ctrod 


counter 
=cirt 


Countercmd 18 the command function for counter. It allocates a structure for the 


691 


new counter and initializes its value to 0. Then it creates a name for the 
counter using the static variable ia, arranges for that name to be returned as 
the command’s result, and increments ia so that the next new counter will get 
a different name. 

This example uses the “object-oriented” style described in Section 30.3, 
where there is one command for each counter object. As part of creating a 
new counter, countercma creates a new Tcl command named after the counter. 
It uses the address of the counter structure as the ciientpata for the command 
and specifies peictecounter aS the deletion callback for the new command. 
Counters can be manipulated by invoking the commands named after them. 
Each counter supports two options to its command: get, which returns the 
current value of the counter, and next, which increments the counter’s value. 
Once ctro and ctri are created, as shown earlier, the following Tel 
commands can be invoked: 


ctroO next; ctrd next; ctrd get 


— or: 
ctrl get 
— sf 
ctroO clear 
= bad counter command "clear": should be get or next 


The function opjectcma implements the Tcl commands for all existing 
counters. It is passed a different c1ientpata argument for each counter, which 
it casts back to a value of type counter *. objectcma Checks opjvii) to see which 
command option was invoked. If it was get, it returns the counter’s value as 
an integer object; if it was next, it increments the counter’s value and does 
not set a result in the interpreter. If an unknown command was invoked, 
objectcma Calls tc1_appendstringstoob} together with 1c1_setopjresuit to create an 
error message. 

To destroy a counter from Tcl you can delete its Tcl command; for example: 


rename ctr0 {} 


As part of deleting the command, Tcl invokes be1eterroc, which frees up the 
memory associated with the counter. 

This object-oriented implementation of counter objects is similar to Tk’s 
implementation of widgets: there is one Tcl command to create a new 
instance of a counter or widget, and one Tcl command for each existing 
counter or widget. A single command function implements all of the counter 
or widget commands for a particular type of object, receiving a clientpata 
argument that identifies a specific counter or widget. A different mechanism 
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is used to delete Tk widgets than to delete counters as shown earlier, but in 
both cases the command corresponding to the object is deleted at the same 
time as the object. 


35.8 Deleting Commands 


Tcl commands can be removed from an interpreter by calling 
Tcl _DeleteCommand (this function is the same for both object-based commands 
and old string-based commands). For example, the following statement 
deletes the ctro command in the same way as the rename command used 
earlier: 


Tcel_DeleteCommand(interp, "ctr0"); 


If the command has a deletion callback, it is invoked before the command is 
removed. Any command may be deleted, including built-in commands, 
application-specific commands, and Tcl procedures. 

In the counter implementation, it would also be possible to provide a 
“delete” method in ovjectcma that deletes the command, like so: 


Tcl_DeleteCommand(interp, Tcl_GetString(objv[0])); 


It is also possible to delete a command using the token returned by 


Tcl_CreateObjCommand: 


Tcl_DeleteCommandFromToken(Tcl_ Interp *interp, 
Tcl_ Command token); 


This works even if the command has been renamed. 


35.9 Fetching and Setting Command Parameters 


The Tcl library provides several functions for fetching and storing 
information about commands. The tc1 cetcommanainfo and tcl setcommandInfo 
calls work with the tci_cmatnfo Structure, which has the following fields: 
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typedef struct Tcl CmdInfo { 
int isNativeObjectProc; 
Tcl ObjCmdProc *objProc; 
ClientData objClientData; 
Tcl _CmdProc *proc; 
ClientData clientData; 
Tcl CmdDeleteProc *deleteProc; 
ClientData deleteData; 
Tcl Namespace *namespacePtr; 
} Tcl_CmdInfo; 


The fields have the following meanings: 


° isNativeObjectProc 


Boolean value equal to 1 if the command was created with the “object API” 
Tol _CreateObjCommand, OF o if it is not object-based and was created with the 
“string APT” tc1_createcommana Call. If this field is true, it is likely to be faster 
to call objproc instead Of proc. 


© objProc 


A pointer to the function that implements the command. 

© objClientData 
Client data for the object API version of the command. 

® proc 
If this command was created with tci_createcommana, this points to the function 
that implements the command. If the command was brought into existance by 
Tcl _CreateObjCommand, this is simply a function that exists to provide 
compatibility with the older string API implementation. 


® clientData 


Client data for the string API command. 
® deleteProc 
This function is the same for both object and string API-derived commands 
and points to the function called when the command is deleted. 
® deleteData 
The ciientpata value passed to deteteProc. 


® namespacePtr 


A pointer to the namespace that the command 1s in. 
The following command function clones a command by fetching information 
about one command using tc1_cetcommandinfo and creating the new command: 
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static int 
CloneCmd(ClientData clientData, Tcl _Interp *interp, 
int objc, Tcl_Obj *CONST objv[])} { 
char *oldCmdName; 
char *newCmdName; 
Tcl_CmdInfo cmdinfo; 
if (objec != 3) { 
Tcl WrongNumArgs(interp, i, objv, 
"oldCmdName newCmdName") ; 
return TCL ERROR; 
} 
oldCmdName = Tel _ GetString(objv[1i]); 
newCmdName = Tcl GetString(objv[2]); 
if (Tcl_GetCommandInfo ( 
interp, oldCmdName, &cmdinfo) == 0) { 
Tcl AppendResult (interp, 
"Command not found: ", 
oldCmdName, NULL) ; 
return TCL_ERROR; 


} 


Tcl CreateObjCommand(interp, newCmdName, 
cmdinfo.objProc, 
emdinfo,objClientData, 
cmdinfo.deleteProc} ; 

return TCL OK; 


} 


In this code, ciacmaname 1s the command to be cloned, for example, expr. The 
function raises an error if a valid name is not provided and tc1_cetcommandtnfo 
returns 0. newcmaName 1§ the name of a new command to create with the same 
functionality as the existing command. 

The same result could be achieved by replacing the rc1_createobjcommana With 
the following code: 


Tcl CreateObjCommand(interp, newCmdName, 
(Tcl ObjCmdProc *}NULL, 
(ClientData) NULL, 
(Tcl _CmdDeleteProc *)NULL) ; 
Tcl _SetCommandinfo(interp, newCmdName, &cmdinfo) ; 


This creates an “empty” command and then sets it to use the data contained 
in the cmainfo Structure. 

In addition to looking up commands by their names, it’s also possible to 
look them up via tokens. There are two ways to obtain a token for a given 
command. If you want to be certain you always have a token for a given 
command, you should store the token returned by 1c1_createoojcommana. This 
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always points to that command, even if it is renamed. You can also retrieve 
the token associated with a command name with the tc1_ cetcommanarromob} 
function. As an example, this code gets the information for the puts 
command: 


Tcl_ Command token; 
token = Tcl GetCommandFrom0bj ( 


interp, Tcl NewStringObj("puts", -1)); 


The commands that use tc1 commana tokens to fetch and set command 
parameters are essentially the same as those described previously and are 
listed in Section 35.1. 


35.10 How Tcl Procedures Work 


All Tcl commands, including those in the Tcl core such as set, it, and proc, 
use the mechanism described in this chapter. 


Note 


In reality, the most common commands are bytecode-compiled, but that 
is an internal optimization not covered in this book. 


For example, consider the creation and execution of a Tcl procedure: 


proc inc {x} { expr { $x +1 } } 
inc 23 
=> 24 


When the proc command is evaluated, Tcl invokes its command function. The 
proc COmmand function is part of the Tcl library, but it has the same 
arguments and results as described in Section 35.2. The proc command 
function allocates a new data structure to describe inc, including information 
about inc’s arguments and body. Then the proc command function invokes 
Tcl_CreateObjCommand to create the Tcl command for inc. It specifies a special 
function called tc1opjinterpproc (which is an internal part of the Tcl library) 
as the command function for inc, and it uses the address of the new data 
structure as the ciientpata for the command. Then the proc command function 
returns. 


696 


When the inc procedure is evaluated, Tcl invokes tciopjinterpproc as the 
command function for the command. tciopjinterpproc USES ItS clientData 
argument to gain access to the data structure for inc and then byte-compiles 
the body of the procedure if necessary. Subsequently, rcicomprvaion; (another 
function internal to the Tcl library) evaluates inc’s body. Before calling 
TclCompEvalObj, TclObjInterpProc Creates a new variable scope for the procedure, 
uses its opjv argument to retrieve the first argument to the inc command, and 
assigns this value to the x variable in the new scope. When the tcicompzvaion} 
call completes, tciopjinterpproc destroys the procedure’s variable scope and 
returns the completion code from teicompzvaionj. All Tcl procedures have 
TclObjInterpProc aS their command function. However, each Tcl procedure has 
a different ciientpata, which refers to the unique structure describing that 
procedure. 


35.11 Command Traces 


In addition to being able to trace variable access, as discussed in Section 
34.6, it is also possible to trace command execution in Tcl. The basic 
method of doing this is via the tc1 createopjrrace function, which creates a 
trace function with the following signature: 


typedef int Tcl_CmdObjTraceProc { 
ClientData clientData, 
Tcl_Interp* interp, 
int level, 
CONST char* command, 
Tcl Command commandToken, 
int objc, 
Tcl Obj *CONST objv{] 


This is useful for creating low-level Tcl debuggers, because at each step of 
the program you can examine the command that’s about to be executed, the 
program’s state, and so on. This is a very powerful feature, although do 
keep in mind that because using it turns off Tcl’s bytecode compiler, it 
notably slows down execution of Tcl code. 
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36. Extensions 


Chapter 30 compared the approach of embedding Tcl into an existing 
application versus extending Tcl with custom commands. It’s usually easier, 
and faster in terms of programmer time, to code a few extensions in C for an 
application written in Tcl, rather than write the application in C and call Tcl 
scripts from it. Writing an extension minimizes the amount of C 
programming compared to Tcl programming, making for better use of 
programmer time. 

This chapter explains how to write a Tcl extension in C. 


36.1 Functions Presented in This Chapter 


® CONST char *Tcl PkgPresent(Tcl_Interp *interp, 


CONST char *name, CONST char *version, int exact) 


CONST char *Tcl PkgRequire(Tcl_ Interp *interp, 


CONST char *name, CONST char *version, int exact) 
Equivalent to the package present and package require Commands, respectively. 
Returns a pointer to the version string for the version of the package that is 
provided in the interpreter (which may be different from version); 1f an error 
occurs, it returns nur and leaves an error message in the interpreter’s result. 
® int Tcl PkgProvide(Tcl_ Interp *interp, 
CONST char *name, CONST char *version) 
Equivalent to the package provide command. Returns rcz ox if it completes 
successfully; if an error occurs, it returns tc. error and leaves an error 


message in the interpreter’s result. 


® CONST char *Tcl_ PkgRequireEx(Tcl Interp *interp, 
CONST char *name, CONST char *version, int exact, 


ClientData *clientDataPtr) 
CONST char *Tcl PkgPresentEx(Tcl Interp *interp, 


CONST char *name, CONST char *version, int exact, 


ClientData *clientDataPtr) 


int Tcl _PkgProvideEx(Tcl_Interp *interp, 
CONST char *name, CONST char *version 
ClientData clientData) 
These calls are identical to the previous versions, but allow the setting and 
retrieving of the client data associated with the package. 
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® CONST char *Tcl_ InitStubs(Tcl_Interp *interp 
CONST char *version, int exact) 
This function must be the first one called from the Tcl library in an extension 
compiled with Tcl stubs. It attempts to initialize the stub table pointers. 


36.2 The mit Function 


In practical terms, an extension is a shared library that is loaded into Tcl at 
runtime with the ioaa command, which is commonly wrapped in some Tcl 
code in order to make it possible to load C extensions in the same way as 
pure Tcl extensions—with a command like package require xyz. Being shared 
objects, extensions are recognizable by the file name extension on the 
platform in question. Extension files end in .ai1 on Windows and .so on most 
Unix systems. 

Tcl extensions are usually based around one or more new Tcl commands that 
provide functionality not available in the Tcl core. Proper extensions are 
written as packages, just as if they were packages of Tcl scripts. 

The entry point for any extension is its mit function, which takes the form 


int Myextension Init(Tcl Interp *interp) { 


} 


The function name, wyextension init In this case, must take the form 
Packagename Init. Packagename COrresponds to the extension’s file name: an 
extension named 1ibpackagename.so MUSt USE Packagename Init aS 1tS mit function, 
and an extension with the tit function roopackage nit must be named 
libFoopackage.so. This is so that Tcl can determine the tit function’s name and 
then call it, knowing only the shared library file name. In reality, it is 
possible to get around this requirement, but it’s a good idea to stick to the 
convention, as it makes things easier. 

The tit function is called when the extension is loaded and is run only 
once, even if the file 1s loaded multiple times. This function is where all 
setup takes place—commands are registered, variables are created, and 
data structures are initialized. For example, if you want to create a hash 
table to track a particular kind of object, create it in the tnit function. 

This function must return tct_ox to indicate success, or rct_ Error 1f something 
went awry. 
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36.3 Packages 


Similar to the pure Tcl package system covered in Chapter 14, compiled 
extensions offer a way to proviae a package, based on the tc1_pxgprovide 
function: 


int Tcl PkgProvide(Tcl_interp *interp, char *name, 
char *version); 


The interp argument is an interpreter, name 1s the name of the package, and 
version 1§ a version number string, such as 1.2 or 5.2.7. As with pure Tcl 
packages, the name and version are used when the package require command 
is called in a script. Try to pick a unique name for your package, so as not to 
conflict with other packages. 

Of course, in complex systems, your extension may require other extensions 
to function. It is possible to require other packages via the tc1_pxgRequire 
function: 


Tcl_ PkgRequire(Tcl_Interp *interp, char *name, 
char *version, int exact); 


The name is the name of a package to require. The version number is the 
minimum version of the package that will work. If the exac¢ flag is not o, the 
version number must match exactly; otherwise, any number that is equal to 
or greater than the version provided here satisfies the dependency. 

If you need to associate data with your package, in the form of a ciientpata 
pointer, Tcl provides the 1ci_pxgproviderx aNd 1c1_PkgRequirerx functions. Aside 
from taking a ciientpata argument, they are identical to the function calls 
described previously. 

When creating the code to build and install your Tcl extension (see Chapter 
47), you also need to provide a pxgtnaex.tc1 file similar to the following: 


package ifneeded counter 0.1 \ 
[list load [file join Sdir \ 
libcounter [info sharedlibextension] ] ] 


This is what actually carries out the 1o2a when a script asks for the package 
with package require counter. Automatic generation of pkgIndex.tcl files is 
explained in further detail in Chapter 14. 


36.4 Namespaces 
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Tcl namespaces aid the programmer in modularizing and encapsulating 
code. Tcl namespaces are discussed from the scripting level in Chapter 10. 
In current versions of Tcl there is no C API to the namespace features, but 
there are some work-arounds to create new namespaces from C. 

Creating a command in a namespace automatically creates the namespace as 
well if it does not already exist: 


Tcel_CreateObjCommand(interp, "foo::bar", BarCmd, 
(ClientData) NULL, (Tcl_CmdDeleteProc *) NULL); 


You can also create it with a quick tc1_svai call: 


char *nsscript = "namespace eval ::foo {}"5 
Tcl_Eval(interp, nsscript); 


If you are just providing a command or two, you probably don't need to 
create a namespace, but if you have many commands, and especially if you 
are creating lots of variables, consider using a namespace in order to spare 
other programmers the chore of looking after too many commands in the 
global namespace. 


36.5 Tel Stubs 


Tcl provides a mechanism to ensure that an extension functions with 
different versions of Tcl without having to be compiled or linked against 
each one. This greatly increases compatibility between different releases of 
extensions and Tcl versions, which are not required to move in lockstep 
with one another. It does this by performing the symbol table lookups itself 
instead of using the normal shared library mechanism. This double 
indirection is what lets us detach the extension in question from a particular 
version of the Tcl library. The stubs mechanism is invoked in a Tel 
extension via the function tc1_tnitstubs: 


Tcl _InitStubs(Tcl_Interp *interp, 
char “version, int exact); 


The first argument specifies the interpreter in which the extension will be 
loaded. The version string argument specifies the minimum version of Tcl 
required for the extension (the major number of the version must match that 
of the Tcl interpreter). For example, s.3 indicates that the extension needs 
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Tcl version 8.3 or later, whereas s indicates that any version 8 Tel 
interpreter is sufficient. If you want to use a specific version of the Tcl 
library, set the exact flag to 1, requiring that the stubs match one, and only 
one, version of Tcl—although at this point it might make more sense to link 
directly and not use the stubs mechanism. 

Tcl_Initstubs Must be the first call in a Tcl extension that uses stubs; to access 
other functions in the Tcl library, the stubs must be loaded. 

In order to write robust code, it’s usually a good idea to use a #iraer to 
isolate the rci_titstubs call, in case someone compiles the extension without 
the stubs mechanism: 


#ifdef USE_TCL STUBS 
if (Tcl InitStubs(interp, "8", 0) == NULL) { 
return TCL ERROR; 


#endif 


Thus, the use of stubs is determined by a compile-time flag, which is 
covered in greater depth in Chapter 47. 


36.6 The icconsig Extension 


The following source code implements an extension called ifconfig for 
querying the status of network interfaces on a Linux system: 
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/* 
Copyright 2004, David N. Welton <davidw@dedasys.com> 


This code may be used, modified and redistributed under the 
same terms as Tcl itself. 
*/ 


#include <stdlib.h> 
#include <strings.h> 
#include <string.h> 
#include <unistd.h> 
#include <sys/types.h> 
#include <sys/socket.h> 
#include <sys/ioctl.h> 
#finclude <net/if.h> 
#include <netinet/in.h> 
#include <netinet/in.h> 
#include <arpa/inet.h> 


#include <tcl.h> 


#define IFC_BUFLEN 8192 
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ListInterfaces -- 


List available interfaces. 


Results: 
A list of interfaces. 


Side Effects: 
None. 


eh et 8b See 6 BR OS he 


static int ListInterfaces(Tcl_Interp *interp) { 
struct ifconf if_request; 
char *ifc_buffer; 
tntete dy 
int fd; 
T010b} *LEList; 
Tcl_Obj *ifname = NULL; 


/* Allocate space for the interface request. */ 
ifc_buffer = (char *)malloc(IFC_BUFLEN) ; 


bzero(ifc_buffer, IFC_BUFLEN) ; 

bzero(&if_request, sizeof (if_request) ); 

/* We need a socket file descriptor to work with, even if it 
* isn't connected to anything. */ 

fd = socket (AF_INET, SOCK_DGRAM, IPPROTO_IP); 


if_request.ifc_buf = ifc_buffer; 
if_request.ifc_len = IFC_BUFLEN; 


/* Fetch information from the kernel. */ 
ioctl(fd, SIOCGIFCONF, &if_ request) ; 
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iflist = Tcl_NewObj(); 
/* Loop through interfaces. */ 
for (i= 0, j = 0; i < if_request.ifc_len; 
i += sizeof(struct ifreq), j++) { 
/* Fetch interface name, create a new string object. */ 
ifname = Tcl_NewStringObj (if_request.ifc_req[j).ifr_name, 
-1); 


/* Add it to the list. */ 
Tcl _ ListObjAppendElement(interp, iflist, ifname); 


/* Use the list as the result. */ 
Tcl SetObjResult(interp, iflist); 


/* Clean up other resources. */ 
close (fd); 
free(ifc_buffer) ; 


return TCL OK; 


* 


* GetInterface -- 


* 


Fetch information about a particular interface in the form 
of a key/value list suitable for use as an array or dict. 


. 
> 
= 
* Results: 

* A list of keys and their values. 
= 

= 

* 

* 


Side Effects: 
None. 


*“y 

static int GetInterface(Tcl_Interp *interp, 
int objc, 
Tcl_Obj *CONST objv[]) { 


int fd; 


struct ifreq ifreq; 
unsigned char *hw; 
struct sockaddr_in *sin; 
char *itf; 
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char hwaddr [40] ; 
Tcl_Obj ‘addr; 
Tcl Obj *braddr; 
Tcl Obj *netmask; 
Tcl_Obj *result; 


if (objec != 3) { 
Tcl_WrongNumArgs(interp, 2, objv, "“interface") ; 
return TCL ERROR; 


} 


itf = Tcl_GetString(objv[2]); 
fd = socket (AF_INET, SOCK _DGRAM, IPPROTO IP); 
strcpy(ifreq.ifr_name, itf)}; 


/* hardware address */ 

ioctl(fd, SIOCGIFHWADDR, &ifreq); 

hw = ifreq.ifr_hwaddr.sa_ data; 

sprintf (hwaddr, "%02x:%02x:%02x:%02x:%02x:%02x", 
*hw, *(hw + 1), *(hw + 2), *{hw + 3), 
*(hw + 4), *(hw + 5)); 


result = Tcl_NewObj(); 
Tcl _ ListObjAppendElement (interp, result, 
Tcl_NewStringObj ("hwaddr", -1)); 
Tcl_ListObjAppendElement (interp, result, 
Tcl NewStringObj (hwaddr, -1)); 


/* address */ 


if (ioctl(fd, SIOCGIFADDR, &ifreq) == 0) { 
sin = (struct sockaddr_in *})&ifreq.ifr_broadaddr; 
addr = Tcl_NewStringObj (inet_ntoa(sin->sin_addr), -1); 


/* broadcast */ 

ioctl(fd, SIOCGIFBRDADDR, &ifreq); 

sin = (struct sockaddr_in *)&ifreq.ifr_broadaddr; 

braddr = Tcl_NewStringObj (inet_ntoa(sin->sin_addr), -1); 


/* netmask */ 
ioctl (fd, SIOCGIFNETMASK, &ifreq); 


sin = (struct sockaddr_in *)&ifreq.ifr_broadaddr; 
netmask = Tcl_NewStringObj (inet_ntoa(sin->sin_addr), -1); 
} else { 


addr = Tcl_NewObj(); 
braddr = Tcl_NewObj(); 
netmask = Tcl_NewObj(); 
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* 


* 


*_ re © + * © © © & 


Tcl_ListObjAppendElement (interp, result, 
Tcl_NewStringObj ("addr", -1)); 
Tcl_ListObjAppendElement (interp, result, addr) ; 
Tcl _ListObjAppendElement (interp, result, 
Tcl_NewStringObj ("braddr", -1)); 
Tcl_ListObjAppendElement (interp, result, braddr); 
Tcl _ ListObjAppendElement (interp, result, 
Tcl_NewStringObj ("netmask", -1)); 
Tcl_ListObjAppendElement (interp, result, netmask) ; 


/* flags */ 
ioctl(fd, SIOCGIFFLAGS, &ifreq); 


Tcl_ListObjAppendElement (interp, result, 
Tcl_NewStringObj("up", -1)); 

Tcl_ListObjAppendElement (interp, result, 
Tcl_NewBooleanObj ( 
(ifreq.ifr_flags & IFF_UP))); 


Tcl_ListObjAppendElement (interp, result, 
Tel _NewStringObj("running", -1)); 
Tcl_ListObjAppendElement(interp, result, 
Tcl_NewBooleanObj ( 
(ifreq.ifr_flags & IFF_RUNNING) )); 


Tcl_ListObjAppendElement (interp, result, 
Tcl_NewStringObj("noarp", -1)); 

Tcl _ListObjAppendElement (interp, result, 
Tcl_NewBooleanObj ( 
(ifreq.ifr_flags & IFF_NOARP))); 


close(fd) ; 


Tcl_SetObjResult(interp, result); 
return TCL_OK; 


Ifconfig -- 

The main function, which calls secondary functions depending 
on the "subcommand". 
Results: 

Depends on the function requested. 
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* Side Effects: 
* None. 


static int Ifconfig(ClientData clientData, 
Tcl_Interp *interp, 
int objc, 
Tcl_ Obj *CONST objv{]) { 
char *subcmd; 
if (objec < 2) { 
Tcl_WrongNumArgs(interp, 1, objv, “list | get | set"); 
return TCL ERROR; 


} 
subcmd = Tcl_GetString(objv[1]); 


if (strcmp(subcmd, "list") == 0) { 
return ListInterfaces(interp) ; 
} else if (stremp(subemd, "get") == 0) { 
return GetInterface(interp, objc, objv); 
} else { 
return TCL ERROR; 


} 
return TCL_OK; 
} 
/ * 
6 ant 8 OO BOS OEE HES SS SSS SSEBSSSEASSST SSSA SDSS HROSSHASSSEBRHABH ADS Ana ses 
* 
* Tclifconfig_Init -- 
* 
* Initializes the package, creating the ifconfig command. 
* 
* Results: 
* None. 
* 
* Side Effects: 
* Creates ifconfig command and package. 
* 
0 in te 8 6.660 OS OSS 6 6 OSS 6 OES HH OO SS6 SH SSESOSSSSSSSHOESSOEHHEBH EO RHEBOHOESE 
=F 
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int Tclifconfig_Init(Tcl_Interp *interp) { 


#ifdef USE_TCL_STUBS 
if (Tcl _InitStubs(interp, "8", 0) == NULL) { 
return TCL ERROR; 


} 


#endif 


/* Create the command. */ 
Tcl CreateObjCommand(interp, "ifconfig", Ifconfig, 
(ClientData) NULL, (Tel _CmdDeleteProc *) NULL); 


if ( Tcl _PkgProvide(interp, 
tiftconfig", 
"O.1") J= TCL_OK ) { 
return TCL ERROR; 


} 


return TCL OK; 


} 


Consider the mit function. The compiled name of this library in Linux is 
libtclifconfig.so, SO tclifconfig Corresponds to telifconfig In the tclifconfig Init 
function. When Tcl loads this library, it looks for this function based on the 
name of the shared library. At that point, depending on whether we 
compiled with the usz_rc1_sruss flag, we may or may not load the stub table. 
The next order of business is to create the irconrig command. We associate it 
with the trcontig function using rci_createopjcommana, Which also registers the 
ifconfig Command for use from within Tcl scripts. 

The 1ci_pkgprovide call that comes next registers the extension as the iscontig 
package—not to be confused with the command—and sets the version to 
0.1. 

The tnit function must return a rct ox, or else the extension fails to load. 
After compiling the extension, we can use the new ifconfig command to 
gather information about network interfaces on a Linux system: 


load ./libtclifconfig.so 
ifconfig list 
= lio ethd ethi 
ifconfig get ame 
= hwaddr 00:02:2d: dipoles addr 10.0.0.10 braddr 10.255.255.255 
netmask 255 255.2 .0 up 1 running 64 
noarp 0 
array set ethl [ifconfig get eth1] 
set ethl (hwaddr} 
= 00:02:2d:1f:41:46 


All things considered, the source code, with comments, weighs in at less 


710 


than 300 lines of C and returns data in a form that we can use very easily in 
Tel. 

By way of comparison, consider another way of performing the same task, 
parsing the output of the /sbin/itcontig command. In that case you must be 
absolutely sure that the output format will not change from version to 
version or among different platforms. If it does change, your script may have 
to deal with mistaken information. Our Tcl/C extension requires some cross- 
platform dexterity (itaers) of 1ts own, but on the other hand, it’s very fast, 
and there is no parsing involved—the data is immediately ready to use with 
other Tcl commands. 

To package this code for distribution, it would be a good idea to create a 
pkgIndex.tcl file along these lines: 


if {[catch {package present ifconfig 1.0}]} { return } 
package ifneeded ifconfig 1.0 [list load \ 
[file join /usr/lib libifconfigl.0.so.0] Tk) 
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37. Embedding Tcl 


Embedding is the practice of using Tcl from within an existing application 
written in C. This chapter explains how to add Tcl to your application, as 
well as how to create new tcisn-style applications. 


37.1 Functions Presented in This Chapter 


® void Tcl FindExecutable (argv[0]) 


Computes the path of the executable, which is needed for several 
mechanisms internal to Tcl. 
® CONST char *Tcl_GetNameOfExecutable() 


Returns a path to the full path name of the application. 


int Tcl_Init(Tcl_Interp *interp) 
Carries out various Tel initialization tasks, such as sourcing Tcl’s own 
init.tcl. 
* int Tcl AppInit(Tcl_Interp *interp) 
User-supplied hook procedure used in the creation of new ¢tcisn-style 


programs. 


37.2 Adding Tel to an Application 


If you’re creating a new application from scratch, it may be worth 
considering writing the application in Tcl, but for many reasons this might 
not be an option. Embedding Tcl in existing applications is easy—with a 
little bit of code, it’s possible to make an application far more powerful by 
giving it a Tcl interpreter. In the extension model we saw earlier, most of the 
code is written in Tcl, and extensions written in C are added as needed to 
provide additional functionality or speed. In the “embedding” model, Tcl is 
just another library that’s linked in to the main application to provide a 
service, in this case, the evaluation of Tcl scripts. 

For example, you could take a web server and add Tcl to it, allowing users 
to create dynamic web pages in Tcl. This is the approach that AOLserver 
and the various Apache Tel projects have taken. The open-source 
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PostgreSQL database lets you use Tcl to write functions and trigger 
procedures. There are countless other examples of large, complex programs 
that have given users the ability to script new and interesting tools with Tcl. 
A lot of value can be added to a program if it has a powerful scripting 
interface. Your users will be able to create and share code—perhaps they 
will even discover innovative ways of hooking the product to other systems 
through Tcl. 

Chapter 31 contains an extremely simple application that evaluates a Tcl 
script contained ina file. Embedding Tcl doesn’t require much more work. 
You need to choose a point in the life cycle of your application where you 
want to initialize Tcl. For instance, you may wish to use Tel as a 
configuration language—you could start Tcl, and then use it to read in a file 
that sets options for your system, such as 


set port 80 
set hostname "www.tcl.tk" 
set errorlog /var/log/myserver/error.log 


Alternatively, you could create some commands so that you don’t even have 
to treat these configuration options like variables: 


port 80 
hostname "www.tcl.tk" 
errorlog /var/log/server/error.log 


The command itself sets the variable internal to your application when it is 
called. If you already have a configuration system, you may wish to delay 
Tcl startup until you can set up the Tcl environment to reflect the information 
about the system it’s running in; at that point you might set some Tcl 
variables and vary behavior depending on how the system has been 
configured. 


37.3 Initialize Tel 


To evaluate Tcl code, you need to call the following setup functions: 
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Tcl Interp *interp; 
Tcl FindExecutable(argv[0] ); 


interp = Tcl _CreateInterp(); 
if (interp == NULL) 
fprintf(stderr, "Tcl Interp creation failed, exiting\n"); 
exit (1); 
| 
S 
if (Tcl_Init(interp) == TCL ERROR) { 
fprintf(stderr, "Tcl Init failed, exiting\n") ; 
exit (1); 


You should call rci_rinazxecutable before any other function of the Tcl library, 
passing it arov(o) as its argument, to help the Tcl runtime to initialize itself. 
Then you can create an interpreter with tc1 createinterp, aS described in 
Chapter 31. If either the interpreter creation or the next call, tc1 mit, should 
fail, your system has a problem, and you may wish to abort the application, 
as you will not be able to use Tel inside it. rci tit 1s the function 
responsible for finding and evaluating the init.tci script that is distributed as 
a part of Tcl. Failure in any of these functions may indicate that you have not 
installed Tcl correctly. 

The Tcl library is now ready to evaluate Tcl scripts. In the same location in 
your C code you should probably take care of any other initialization that 
you need, such as the creation of commands, variables, channels, and so on. 
If you are using multiple interpreters, you may want to initialize them first 
and then, in each interpreter that needs it, perform the setup tasks, as it is 
currently not possible to copy an interpreter’s state (commands, variables, 
and so on). 

The second decision you have to make, after having placed the Tcl 
initialization code in your application, is when to evaluate Tcl scripts. For 
some applications it’s obvious when this needs to happen. In a web server 
that uses Tcl to dynamically generate pages, a Tcl script is evaluated when 
the user requests some resource (usually a web page). If the user has 
requested, say, indaex.tc1, the web server is responsible for executing that Tcl 
code and sending the HTML results back to the user. Other applications may 
need to add more complex hooks, such as working with Tcl’s event loop 
(described in Chapter 43). However, at some point your application will 
call one of the functions in the tc1_2va1 family to process Tcl code. 
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37.4 Creating New Tel Shells 


Before Tcl gained the ability to load shared library extensions, a popular 
way of enhancing the language’s functionality was to create new versions of 
the Tcl shell (¢cisn) with the desired functionality added in. This is a special 
case of “embedding” where the only functionality of the C “application” is 
to set up and run Tcl code. The drawback to this approach is that you may 
want to use more than one extension, and at this point you would need to 
either integrate and compile both extensions or load one of them. Loading 
extensions dynamically is a far more flexible approach. 

There may be situations where old code is involved or where you wish to 
have one statically linked executable with no libraries to load. In those 
cases, creating your own Tcl shell may be the best approach, although even 
here solutions like Starkits (described in Chapter 14) may be preferable. 
You should also be aware of the differences between the Tcl library and the 
tclsh program. tcish provides several variables that are not set up by the Tcl 
library, including argc, argv, argvo, and tcl interactive, which are covered in 
Chapter 3. Additionally, tcisn sources a “dot-file,” .tcisnre. If you wish to 
create a shell of your own, you most likely want to copy this behavior, so 
that your shell behaves like tcisn. 

The means that Tcl provides to accomplish this is the tc1 apptnit function. 
Tcl_Apptnit 18 a function that performs application-specific initialization, such 
as creating new commands. The main functions for tcish and wisn invoke 
Tcl _Appinit after they have performed all of their own initializations, but 
before they start evaluating Tcl scripts. The overall idea is for the function 
main to carry out functions that are the same in all tcisn-like (or wisn-like) 
applications, while vci apprnit carries out the functions that may differ from 
application to application. 

The version of tc1_apprnit used by tcisn looks like this: 


int Tcl_AppInit(Tcl_Interp *interp) { 
if (Tcl_Init(interp) == TCL ERROR) { 
return TCL ERROR; 


tcl RcFileName = "~/.tclshre"; 
return TCL OK; 
} 
Tcl_AppiInit 18 invoked with a single argument consisting of the Tcl interpreter 


for the application. If tci apptnit completes normally, it returns tc._ox, and if 
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it encounters an error, it returns tc. error and sets a result in the interpreter 
(in this case the application prints the error message and exits). This 
particular version of tc1 appinit does two things. First, it calls the function 
tcl tnit, Which performs additional Tcl initialization (it sources a script 
from the Tcl library to define the unknown procedure and set up the 
autoloading mechanism, described in Chapter 14). The argument and result 
for tci_tmit are the same as for tc1_apptnit. The second thing rc1 appinit does 
is to set the global variable tci_xcri1ename, Which gives the name of a user- 
specific startup script. This variable is initially set to nurz by the main 
function in the default +cisn and wisn} 1f tc1 apptnit Modifies tci RcFileName, and 
if the application is running interactively (rather than from a script file), main 
sources the file named by tc1_xcriiename. 

To create a new tcisn-Style shell, all you have to do is write your own 
Tcl _Apptnit function and compile it with the Tcl library. For example, you can 
regenerate the tcisn application by making a copy of the file unix/tciapptnit.c 
from the Tcl source directory, which contains the preceding code for 
Tcl Apptnit. Then compile this file and link it with the Tcl library as 
described in Chapter 46: 


cc telAppInit.c -ltcl -lm -o mytclsh 


The resulting application is identical to the system version of tcisn: it 
supports interactive input, script files, and all of the other features of tcisn. 
If you wanted to include the counter package presented in Chapter 35 in your 
application, you might write the following tc1_appinit: 


int Tcl_AppInit(Tcl_Interp *interp) { 
if (Tcl_Init(interp) == TCL_ERROR) { 
return TCL ERROR; 


if (Counter Init(interp) == TCL ERROR) { 
return TCL ERROR; 


} 


tcl _RcFileName = "~/.tclshrc"; 
return TCL OK; 


} 


You would then compile counter.c as part of the application in addition to the 
file containing the rci_apprnit function described previously. 
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38. Exceptions 


Many Tcl commands, such as iz and whiie, have arguments that are Tcl 
scripts. The C functions for these commands evaluate them recursively to 
evaluate the scripts. If rci_evaiopjzx or any of its related evaluation functions 
returns a completion code other than rcz ox, an exception is said to have 
occurred. Exceptions include rct_ error, which was described in Chapter 31, 
plus several others that have not been mentioned yet. This chapter 
introduces the full set of exceptions and describes how to unwind nested 
evaluations and leave useful information in the errorinfo and errorcode 
variables. 


38.1 Functions Presented in This Chapter 


° Tcl AddObjErroriInfo(Tcl_ Interp *interp, 


char *message, int length) 


Adds error text to the errortnfo variable. 


id Tcl AddErrorInfo(Tcl_Interp *interp, char *message) 
Like Tcl AddObjErroriInfo, but initializes erroriInfo from the string value of the 
interpreter’s result if the error result is new. 


® Tcl SetObjErrorCode(Tcl_Interp *interp, 
Tcl Obj *errorObjPtr) 
Sets the errorcode variable from errorObjPtr. 


* Tcl SetErrorCode (Tcl Interp *interp, char *element, 
char *element, ... (char *) NULL) 
Sets the errorcode variable from a series of strings. 


® Tcl SetErrorCodeVA(Tcl_Interp *interp, va_list argList) 
Sets the errorcode variable froma va list. 


Tcl Obj *Tcl_GetReturnOptions (Tcl Interp *interp, 
int code) 
Retrieves the dictionary of return options from an interpreter following a 
script evaluation. 
* int Tcl SetReturnOptions(Tcl Interp *interp, 
Tcl Obj *options) 
Sets the return options of interp to be options. 


® CONST char *Tcl PosixError(Tcl Interp *interp) 
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Sets the errorcoae variable after an error in a POSIX kernel call. It reads the 
value of the errno C variable and calls Tcl _SetErrorCode tO Set errorcode in the 
POSIX format. Returns a human-readable diagnostic message for the error. 


void Tcl _LogCommandInfo(Tcl Interp *interp, 
CONST char *script, CONST char *command, 
int commandLength) 
Adds information about the command that was being executed when the 
error occurred to the errortnfo variable, and the line number stored internally 
in the interpreter 1s set. 
® void Tcl _Panic(CONST char *format, arg, arg, ...) 
Prints the formatted error message to the standard error file of the process, 
and then calls aport to terminate the process. tc1_ panic does not return. 
® void Tcl PanicVA(CONST char *format, va_list argList) 
Like tci_panic, but takes a va _1ist argument. 


void Tcl_SetPanicProc(Tcl_ PanicProc panicProc) 


Sets the function to use when 1c1 panic 18 called. 


38.2 Completion Codes 


Table 38.1 lists the full set of completion codes (which are integer return 
values) defined by Tcl. If a command procedure returns anything other than 
rct_ox, Tcl aborts the evaluation of the script containing the command and 
returns the code as the result of 1ci_evaiopjzx (OF Tcl _EvaiFile, etc.). rcn_ox and 
tcL_ERRoR have already been discussed; they are used for normal returns and 
errors respectively. The completion code rc srzax Or tc continue OCCUrs If a 
break OF continue Command is invoked by a script; in both of these cases the 
interpreter’s result is an empty string. The rct_ return completion code occurs 
if return 18 Invoked; in this case the interpreter’s result is the intended result 
of the enclosing procedure. Additional completion codes may be defined by 
application-specific commands. 


Table 38.1 Completion Codes Returned by Functions That Evaluate Scripts 
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Completion code Meaning 


TCL_OK Command completed normally. 
TCL_ERROR Unrecoverable error occurred. 

TCL BREAK break command was invoked. 
TCL_CONTINUE cont inue command was invoked. 
TCL_RETURN return command was invoked. 
anything else Defined by application. 


As an example of how to generate a rct_sreax completion code, here is the 
command procedure for the preax command: 


int Tcl BreakObjCmd(dummy, interp, objc, objv) 


ClientData dummy; /* Not used. */ 
Tcl Interp *interp; /* Current interpreter. */ 
int objc; /* Number of arguments. */ 


Tcl Obj *CONST objv[]; /* Argument objects. */ 


if (objc != 1) { 
Tel WrongNumArgs(interp, 1, objv, NULL}; 
return TCL ERROR; 


} 


return TCL BREAK; 


} 


In reality, in code that has been bytecode-compiled, things work a little 
differently, and the command gets called only if compilation doesn’t take 
place. However, it is a good example. 

TCL BREAK, TCL CONTINUE, @Nd ci return are used to unwind nested script 
evaluations back to an enclosing looping command or procedure invocation. 
Under most circumstances a procedure that receives any completion code 
other than rect ox from tc1_zvaiopjzx Should immediately return that same 
completion code to its caller without modifying the interpreter’s result. 
However, a few commands process some of the special completion codes 
without returning them upward. For example, here is an implementation of 
the waite command: 
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After checking its argument count, 
iteration evaluates the command’s 


int Tcl _Whil 
ClientDa 
Tcl_Inte 
int objc 
Tel Obj 


eObjCmd(dummy, interp, 


objc, objv) 


ta dummy; /* Not used. */ 

rp *interp; /* Current interpreter. */ 
: /* Number of arguments. */ 
*CONST objv[]; /* Argument objects. */ 


int result, value; 


if (objec 
TeL: 

" 

retu 


} 


while (1 


f= 3) { 


4 


WrongNumArgs(interp, 1, objv, 


test command"); 
rn TCL ERROR; 


1 f 
) { 


/* Get the results of the expression which 
indicates whether to continue or not. */ 
lt = Tcl_ExprBooleanObj{interp, objv[i], 


resu 
Hh 


} 


we of 


result != TCL_OK) 
return result; 


value == 0) { 
return TCL OK; 


&value) ; 


/* Evaluate the while body. */ 
lt = Tcl_EvalObjEx(interp, objv[2], 0); 
if (result == TCL CONTINUE) { 


resu 


} el 
} el 
} 

} 


continue; 


se if (code == TCL BREAK) { 


return TCL OK; 
se if (code != TCL OK) 
return code; 


{ 


Tcl_Whileobjcma enters a loop where each 
first argument as an expression and its 


second argument as a script. If an error occurs while the expression is being 
evaluated, tci_ whileopjcma returns the error. If the expression evaluates 
successfully but its value is o, the command terminates with a normal return. 
Otherwise, it evaluates the script argument. If the completion code is 


TCL 


TCL 


CONTINUE, Tcl_Whi 


to 


Tcl 


its caller. If Tel - 


unwinding to occur on the rc error OF TcL_RI 
any new completion codes are added in the future. 
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leobjcma Goes on to the next loop iteration. If the code is 
BREAK, Tcl _wWhileobjcma ends the execution of the command and returns tc1 ox 
evalobjex returns any other completion code besides cz. ox, 
| whileobjcma Simply reflects that code upward. This causes the proper 


eturn code and it also unwinds if 


If an exceptional return unwinds all the way through the topmost script being 
evaluated, Tcl checks the completion code to be sure it is either rc1 ox or 
tc. ERRor. If another code is returned, Tcl turns the return into an error with 
an appropriate error message. Furthermore, if a rct srzax OF TCL CONTINUE 
exception unwinds all the way out of a procedure, Tcl also turns it into an 
error; for example: 


break 

=> invoked "break" outside of a loop 
proc badbreak {} {break} 
badbreak 

= invoked "break" outside of a loop 


Thus, applications need not worry about completion codes other than tc1_ox 
and tc._zrror When evaluating scripts from the topmost level. It is possible to 
circumvent this behavior with the 1c1 allowzxceptions function, covered in the 
reference documentation. 


38.3 Setting errorCode 


The last piece of information set after an error is the errorcode variable, 
which provides information about the error in a form that’s easy to process 
with Tcl scripts—errorinfo (See below) is really meant to be read by people, 
not programs. It is intended for use in situations where a script is likely to 
catch the error, determine what went wrong, and attempt to recover from it 
if possible. If a command procedure returns an error to Tcl without setting 
errorcode, Tcl sets it to none. If a command procedure wishes to provide 
information in errorcode, 1t should invoke either ci setErrorcode OF 
Tcl_SetObjErrorcode before returning tci_ERRor. 

Tcl_SetErrorcode takes as arguments an interpreter, any number of string 
arguments, and then a null pointer. It forms the strings into a list and stores 
the list as the value of errorcoae. For example, suppose that you have written 
several commands to implement gizmo objects, and that there are several 
errors that could occur in commands that manipulate the objects, such as an 
attempt to use a nonexistent object. If one of your command procedures 
detects a nonexistent object error, it might set errorcode aS follows: 


Tel SetErrorCode(interp, "GIZMO", "EXIST", 
"no object by that name", 
(char *) NULL); 
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This will leave the value crzmo extst {no object by that name} IN errorCode. GIZMO 
identifies a general class of errors (those associated with gizmo objects), 
extst 18 the symbolic name for the particular error that occurred, and the last 
element of the list is a human-readable error message. You can store 
whatever you want 1M errorcode aS long as the first list element doesn’t 
conflict with other values already in use, but the overall idea is to provide 
symbolic information that can easily be processed by a Tel script. For 
example, a script that accesses gizmos might catch errors, and if the error is 
a nonexistent gizmo, it might automatically create a new gizmo. 

The object version 1§ tc1_setobjzrrorCode! 


Tel SetObjErrorCode(Tcl_ Interp *interp, Tcl Obj 
*errorListOb)); 


where errornistobj 18 a Tel list similar in form to the list that rc1 setzrrorcode 
takes: 


Tel Obj *err; 
err = Tcl NewObj(); 
Tcl ListObjAppendElement ( 

interp, err, Tcl_NewStringObj ("GIZMO", -1)); 
Tcl ListObjAppendElement ( 

interp, err, Tcl NewStringObj("EXISTS", -1}}; 
Tcl ListObjAppendElement ( 

interp, err, Tcl_NewStringObj ( 

"no object by that name", -1)); 

Tcl _SetObjErrorCode(interp, err); 


It’s probably easier to use the non-object version in this case unless you 
need to directly insert numbers into the list. One would hope that errors are 
rare enough that the performance penalty incurred by the non-object code is 
not noticeable. 


38.4 Managing the Return Options Dictionary 


As mentioned in Chapter 13, it’s possible to provide a return options 
dictionary to the return command in order to pass arbitrary information when 
raising an exception. The catcn command can then retrieve the return options 
dictionary and process it in any way desired. 

The equivalent method of accomplishing the same thing from within C code 
iS tO USE Tcl _setReturnoptions to set the return options dictionary and 
Tcl_GetReturnOptions to retrieve it. 
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A typical usage for tc1_cetreturnoptions 18 to retrieve the stack trace when 
script evaluation returns an error, like so: 


int code = Tcl Eval(interp, script); 


if (code == TCL_ERROR) { 
Tcl_Obj *options = Tcl _GetReturnOptions(interp, code); 
Tcl Obj *key = Tcl _NewStringObj("-errorinfo", -1); 


Tcl _ Obj *stackTrace; 

Tcl_IncrRefCount (key) ; 

Tcl DictObjGet (NULL, options, key, &stackTrace) ; 
Tcl DecrRefCount (key) ; 

/* Do something with stackTrace. */ 


This takes the dictionary object options and returns the value of the -erroringo 
key, which should be a stack trace detailing what went wrong when script 
was evaluated. 


38.5 Adding to the Stack Trace in erroriInfo 


When an error occurs, Tcl adds a description of it to the stack trace of the 
commands that were being evaluated at the time of the error; this stack trace 
is visible to the user in the errorinfo global variable. Tcl accomplishes this 
by calling the procedure tc1_addopjzrrorinfo OF Tcl _AddErrorinfo, both of which 
have the following prototypes: 


void Tcl _AddObjErroriInfo(Tcl_Interp *interp, 
char *message, int length) ; 
void Tcl AddErroriInfo(Tcl _Interp *interp, 
char *message) ; 


The difference 1s that message IN Tcl AddobjErrorInfo Can contain embedded 
nulls. For most purposes, it’s simpler to just use tc1_Addzrrorinfo. 

The first call to tc1 aaazrrorinfo after an error has occurred sets errorinfo to 
the error message stored in the interpreter and then appends message. Each 
subsequent call for the same error appends message tO errortnfo’S Current 
value. Whenever a command procedure returns tct error, tcl eval calls 
Tcl_AddErrorinfo to log information about the command that was being 
executed. If there are nested calls to tc evai, each one adds information 
about its command as it unwinds, so that a stack trace forms in errortnfo. 
Command procedures can call tci_addzrrortnfo themselves to provide 
additional information about the context of the error. This is particularly 
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useful for command procedures that invoke tci_evai recursively. For 
example, consider the following Tcl procedure, which is a buggy attempt to 
find the length of the longest element in a list: 


proc longest {list} { 
set i [llength $list] 
while {$i >= 0} { 
set length [string length [lindex Slist $i]] 
if {$length > $max} { 
set max S$length 
} 


cy 9 | acts Rat 
return Smax 


} 


This procedure fails because it never initializes the variable max, so an error 
occurs when the is command attempts to read it. If the procedure 1s invoked 
with the command tongest {a 12345 xyz}, the following stack trace is stored in 
errorinfo after the error: 


can't read "max": no such variable 
while executing 
"if {$length > $max} { 
set max $length 
}n 
(procedure "longest" line 5) 
invoked from within 
“longest {a 12345 xyz}" 


All of the information is provided by tci_zvai except for the line with 
comments in parentheses. The parenthesized message was generated by the 
code that evaluates procedure bodies. 

Keen observers will note that there is no error message for the white 
command in this case. This is because it has been byte-compiled and thus 
doesn’t really exist as a normal procedure. If we could force it to be called 
as a procedure, we would get the following error trace: 
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can't read "max": no such variable 
while executing 
"if {Slength > $max} { 
set max S$length 
\n 
("while" body line 3) 
invoked from within 
"Swhilecmd {$i >= 0} { 
set length [string length [lindex Slist $i]] 
if {$length > $max} { 
set max Slength 
} 
incr i -1 
\n 
(procedure "longest _with_while" line 4) 
invoked from within 
"longest_with_while {a 12345 xyz}" 


Without the bytecode-compiled wiie command, we get a _ second 
parenthesized message, which gives us information on where the error 
occurred within the wniie body. 

If you used the implementation of wniie from Section 38.2, instead of the 
built-in Tcl implementation, the first parenthesized message would be 
missing. The following C code is a replacement for the wni1e loop and the 
code that follows it in ci wnileobjcma; It USES Tcl AppenaResult to add the 
parenthetical remark: 


Ps 


while (1) { 

/* Get the results of the expression which indicates 
whether to continue or not. */ 

result = Tcl_ExprBooleanObj(interp, objv[1], &value); 

if (result != TCL_OK) { 
return result; 

} 

if (!value) { 
break; 


} 


/* Evaluate the while body. */ 
result = Tcl_EvalObjEx(interp, objv[2], 0); 
if ((result != TCL_OK) && 
(result != TCL_CONTINUE)) { 
if (result == TCL_ERROR) { 


Tcl Obj *options = Tcl GetReturnOptions({interp, code) ; 
Tcl_Obj *key = Tcl_NewStringObj("-errorline", -1); 
Tcl_Obj *value; 

int line; 


Tcl_DictObjGet (NULL, options, key, &value); 
Tcl _ GetIntFrom0bj (NULL, value, &line) ; 
Tcl_DecrRefCount (key) ; 

Tcl_DecrRefCount (options) ; 


char msg[32 + TCL_INTEGER_SPACE] ; 
sprintf(msg, "\n (\"while\" body line #d)", line); 
Tcl AddErroriInfo(interp, msg) ; 


} 


break; 


} 
} 


if (result == TCL_BREAK) { 
result = TCL_OK; 
} 


if (result == TCL_OK) { 
Tcl_ResetResult (interp) ; 
} 


return result; 


The -erroriine key of the return options dictionary is set by tc1_zvaiobjrx 
whenever a command procedure returns rci_error; it gives the line number of 
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the command that produced the error. A line number of 1 corresponds to the 
first line of the script being evaluated, which 1s the line containing the open 
brace in this example; the :s command that generated the error is on line 3. 


Note 


Prior to Tcl 8.5, the error line number was available only by accessing 
interp->errorLine directly. This technique is strongly deprecated in Tcl 
8.5 and may be disabled altogether in Tcl 8.6. Any existing code that 
ACCESSES interp->errorLine Should be replaced with code like that shown 
previously to access the -erroriine key from the return options 
dictionary. Future versions of Tcl might provide more direct accessors 
for the line number information; consult the Tcl reference 
documentation for more information. 


For simple Tcl commands you shouldn’t need to invoke ci adazrroringo: the 
information provided by tci_evai 1s sufficient. However, if you write code 
that calls tc1_evai, it’s a good idea to call tc1_addrrrortnfo Whenever tc1_zval 
returns an error, to provide information about why c1_zva1 was invoked and 
also to include the line number of the error. 

You must call tc1 adazrrorinfo rather than trying to set the errortnto variable 
directly, because tci_adazrrortnfo contains special code to detect the first call 
after an error and clear out the old contents of errortnfo. 


3 8 ° 6 Tcl_ Panic 


When the Tcl system encounters an error it can’t handle—running out of 
memory, for example—it calls the rc1_panic function. Normally, this prints an 
error message to the standard error channel and calls abort to end the current 
process. You can use it in your own extensions like so: 


Tcl Panic(CONST char* format, arg, arg, arg, ...); 


format 18 a format string like that in printe, and the aroS are arguments to print 
out. This function does not return, so if you need to call it from your 
extension, be sure it’s the last thing you call. Do not use this function where 
an ordinary error would suffice, but only in cases where the application 
should halt immediately. 
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When Tcl is embedded in an application, you might wish to provide a more 
graceful way of shutting down Tcl and leave the process running, or simply 
let the application shut down according to its own rules. Of course, once 
Tcl_panic has been called, you must ensure that your program does not attempt 
to make further use of Tcl. It is possible to register a function to be called in 
place of the default panicProc USING Tc1_setPanicProc! 


static void 
My Panic TCL_VARARGS DEF(CONST char *, argl) { 


Application-specific shutdown 
fprintf(stderr, 


"Tol has panicked, terminating application\n") ; 
abort (); 


Tcl SetPanicProc(My Panic) ; 


This registers a function that takes care of any cleanup specific to the 
application, prints an error message, and then terminates the process. 
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39. String Utilities 


Tel provides a number of utility functions that make working with strings 
and hash tables considerably easier and that C programmers can mostly use 
(with the exception of the encoding framework and the regular expression 
engine) independently of the rest of the Tcl library. This chapter describes 
Tcl’s library functions for manipulating strings, including a dynamic string 
mechanism that allows you to build up arbitrarily long strings; a function for 
doing simple string matching; a suite of functions for working with Unicode 
characters and UTF-8 strings; and a function for testing the syntactic 
completeness of a command. 


39.1 Functions Presented in This Chapter 


The following string utility functions are described in this chapter: 

® void Tcl DStringInit (Tcl DString *dsPtr) 
Initializes asrer’s value to an empty string (the previous contents of asrtr are 
discarded without cleaning up). 

* char *Tcl DStringAppend(Tcl DString *dsPtr, 

const char *string, int length) 

Appends tengtn bytes from string to asptr’s value and returns the new value of 
dsptr. If 1ength 18 less than 0, appends all of string. 


® char *Tcl DStringAppendElement (Tcl DString *dsPtr, 


const char *string) 

Converts string to a proper list element and appends it to asrer’s value (with 
separator space if needed). Returns the new value of asper. 

* Tcl DStringStartSublist (Tcl DString *dsPtr) 
Adds suitable bytes to asrer ({, for example) to initiate a sublist. 

® Tcl _ DStringEndSublist (Tcl DString *dsPtr) 
Adds suitable bytes to asrer ( }, for example) to terminate a sublist. 

® char *Tcl_DStringValue(Tcl_DString *dsPtr) 
Returns a pointer to the current value of asrer. 

* int Tcl DStringLength(Tcl DString *dsPtr) 
Returns the number of bytes in asrer’s value, not including the terminating 
null byte. 


2 Tcl DStringTrunc (Tcl DString *dsPtr, int newLength) 
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If aseer has more than newrengtn bytes, shortens it to include only the first 
newLength bytes. 

* Tcl DStringFree (Tcl DString *dsPtr) 
Frees up any memory allocated for asr¢r and re-initializes asper’s value to an 
empty string. 

* Tcl DStringResult(Tcl_Interp *interp, Tcl DString *dsPtr) 
Moves the value of asrer to the interpreter’s result and re-initializes asper’s 
value to an empty string. 

* Tcl _DStringGetResult (Tcl _Interp *interp, 

Tel _DString *dsPtr) 

Moves the contents of the interpreter’s result into asPer and re-initializes the 
interpreter’s result to the empty string. 

® int Tcl StringMatch(const char *string, 

const char *pattern) 

Returns 1 1f string matches pattern using glob-style rules for pattern matching, 
o otherwise. 

® int Tcl StringCaseMatch(const char *string, 

const char *pattern, int nocase) 

Returns 1 1f string matches pattern using glob-style rules for pattern matching, 
o Otherwise. If nocase 18 0, the match is performed case-sensitively, and if it is 
i, the match is performed case-insensitively. 


int Tcl RegExpMatchObj (Tcl _Interp *interp, 

Tcl Obj *textObj, Tcl Obj *patObj) 
Tests whether the regular expression 1n patonj matches the string in textovj, 
returning i if they match, o otherwise. If an error occurs while patonj is 
compiling, an error message is left in the interpreter (if non-null) and -: is 
returned. 


int Tcl _RegExpMatch(Tcl Interp *interp, char *text, 

const char *pattern) 
Tests whether the regular expression in pattern matches the string in text, 
returning i if they match, o otherwise. If an error occurs while pattern 1S 
compiling, an error message is left in the interpreter (if non-null) and -: is 
returned. 


® Tcl RegExp Tcl RegExpCompile (Tcl Interp *interp, 


const char *pattern) 
Compiles pattern to a regular expression and returns a handle to it. If an 
error occurs while pattern 18 compiling, an error message is left in the 
interpreter (if non-null) and wozz 1s returned. 


int Tcl RegExpExec(Tcl Interp *interp, Tcl RegExp regexp, 


char *text, char *start) 
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Tests whether the compiled regular expression regexp matches the string text, 
which itself should be a substring of the string stare (information necessary 
for repeated matching). Returns : if there is a match, o if there is no match, 
and -1 if an error occurred (with an error message in the interpreter if that is 
non-null). 


® Tcl _RegExpRange (Tcl RegExp regexp, int index, 


const char **startPtr, const char **endPtr) 
Provides additional information about a subexpression range inaex after a 
successful match against the expression regexp. The startper and enaper 
arguments indicate variables that are set to point to the start and end of the 
matched range respectively. 


® Tcl RegExp Tcl _GetRegExpFromObj (Tcl Interp *interp, 
Tcl Obj *patObj, int cflags) 
Compiles the pattern in paton; to a regular expression, given the compilation 
flags in criags. If an error occurs during compiling, it returns nox. and stores 
an error message in the interpreter. See the reference documentation for a 
description of the supported compilation flags. 


int Tcl_ RegExpExecObj (Tcl _Interp *interp, 


Tcl _RegExp regexp, Tcl Obj *textObj, int offset, 
int nmatches, int eflags) 

Matches a regular expression regexp against a string in textonj, Starting from 
offset Characters into the string. The nmarcnes argument describes the 
maximum number of subexpressions for which information will be 
requested, and eriags gives a number of regular-expression execution flags. 
Returns i if the expression matches, o 1f it does not. If an error occurs during 
matching, it returns -1 and leaves an error message in the interpreter. See the 
reference documentation for a description of the supported execution flags. 


° Tcl RegExpGetInfo(Tcl_ RegExp regexp, 


Tcl RegExpInfo *infoPtr) 
Obtains extended information about the last match of the regular expression 
regexp. The information describes the number of possible subexpressions, the 
number that actually matched, the character location within the string where 
each subexpression matched, and (with correct compilation flags) whether it 
is possible to match the regular expression at all, even with additional text. 


® char *Tcl ExternalToUt£DString(Tcl Encoding encoding, 
const char *src, int srcLen, Tcl DString *dsPtr) 
Converts the character data in src (of length srczen, or up to the first zero byte 
if srcten 18 negative) from the encoding encoding to the UTF-8 encoding used 
internally in Tcl and returns the resulting string. The buffer in asrer 1s used as 
a workspace; it should be released with 1c1 pstringrree once the converted 
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string is no longer required. If encoding 18 nui, the current system encoding is 
used. 


® char *Tcl_UtfToExternalDString(Tcl_ Encoding encoding, 

const char *src, int srcLen, Tcl DString *dsPtr) 
Converts the character data in src (of length srcren, or up to the first zero byte 
if srcten 18 negative) from the UTF-8 encoding used internally in Tcl to the 
encoding encoding and returns the resulting string. The buffer in asper is used 
as a workspace; it should be released with rci_pstringrree once the converted 
string is no longer required. If encoding 1S nui1, the current system encoding is 
used. 


® Tcl Encoding Tcl _GetEncoding(Tcl_ Interp *interp, 
const char *name) 
Returns the encoding called name, or 1f no encoding with that name is known, 
returns nur. and places an error message in the interpreter’s result. The 
returned encoding should be released with tc1_Freezncoding When it is no 
longer required. 


® Tcl _FreeEncoding(Tcl_Encoding encoding) 
Releases an encoding previously returned by tc1_cetEncoding. 

® int Tcl UniCharToUtf(int ch, char *buf) 
Converts cn to UTF-8 and stores it in the buffer at ,ur. Returns the number of 
bytes written. 

* int Tcl _UtfToUniChar (const char *src, Tcl _UniChar *chPtr) 
Converts the first UTF-8 character at src to Unicode and writes it to the 
variable pointed to by cnetr. Returns the number of bytes read. 


® char *Tcl UniCharToUtfDString (const Tcl UniChar *uniStr, 


int uniLength, Tcl DString *dsPtr) 
Converts the string of unitengen Unicode characters at uniser to UTF-8 and 
stores that in the given rc1_pstring. Returns the UTF-8 string produced. 
* Tcl UniChar *Tcl_ UtfToUniCharDString(const char *src, 
int length, Tcl_DString *dsPtr) 
Converts the string of up to tengen UTF-8 characters at src to a Unicode 
string that is stored in the given tc1 pstring. Returns the Unicode string 
produced. If iengen is -1, all UTF-8 characters up to the end of the input 
string are processed. 
® int Tcl_UniCharLen(const Tcl_UniChar *uniStr) 
Returns the length (in Unicode characters) of the null-terminated Unicode 
string 1N unistr. 
® int Tcl _UniCharNemp (const Tcl UniChar *ucs, 


const Tcl UniChar *uct, int numChars) 


Compares the first numcnars characters of two Unicode strings for equality, 
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returning o if they are the same, a negative number if ucs has the smallest 
character at the first place they differ, or a positive number if uct has the 
smallest character at the first place they differ. 
® int Tcl _UniCharNcasecmp (const Tcl _UniChar *ucs, 
const Tcl UniChar *uct, int numChars) 
Case-insensitively compares the first numchars characters of two Unicode 
strings for equality, returning o if they are the same, a negative number if ucs 
has the smallest character at the first place they differ, or a positive number 
if uct has the smallest character at the first place they differ. 
* int Tcl UniCharCaseMatch(const Tcl _UniChar *uniStr, 
const Tcl UniChar *uniPattern, int nocase) 
Returns 1 if uniser matches unirattern using glob-style rules for pattern 
matching, o otherwise. If nocase 18 non-zero, the pattern is compared case- 
insensitively; otherwise it is compared case-sensitively. 
® int Tcl UtfNcemp(const char *cs, const char *ct, 
int numChars) 
Compares the first numchars characters of two UTF-8-encoded strings for 
equality, returning o if they are the same, a negative number if -s has the 
smallest character at the first place they differ, or a positive number if c+ has 
the smallest character at the first place they differ. 
® int Tcl UtfNcasecmp (const char *cs, const char *ct, 
int numChars) 
Case-insensitively compares the first numchars characters of two UTF-8- 
encoded strings for equality, returning o if they are the same, a negative 
number if -s has the smallest character at the first place they differ, or a 
positive number if -t has the smallest character at the first place they differ. 


® int Tcl UtfCharComplete (const char *src, int length) 


Tests if the 1engen bytes (or all the bytes up to the next zero byte if length is 
-1) at src represent at least one UTF-8 character. 


® int Tcl NumUtfChars(const char *srce, int length) 


Returns the number of UTF-8 characters in the string at src. Only the first 
1ength bytes are used, or all bytes up to the first null are used 1f tengtn 1s -1. 

* const char *Tcl UtfFindFirst (const char *src, int ch) 
Returns the first instance of the character cn in the null-terminated UTF-8- 
encoded string src, or nuit 1f the character is not present. 


® const char *Tcl UtfFindLast (const char *src, int ch) 


Returns the last instance of the character cn in the null-terminated UTF-8- 
encoded string src, or nuit 1f the character is not present. 


® const char *Tcl UtfNext (const char *src) 


Returns the location of the next UTF-8 character in the string src. 


736 


® const char *Tcl UtfPrev(const char *src, 


const char *start) 
Returns the location of the previous UTF-8 character before src, where the 
start of the string is pointed to by start. 
® Tcl _UniChar Tcl_UniCharAtIndex(const char *src, int index) 
Returns the inaexth Unicode character extracted from the UTF-8 string src. 
The string must contain at least inaex UTF-8 characters. The index must not 
be negative. 


® const char *Tcl UtfAtIndex(const char *src, int index) 


Returns a pointer to the incesth UTF-8 character in the UTF-8 string src. The 
string must contain at least inaex UTF-8 characters. 
* int Tcl _UtfBackslash(const char *src, int *readPtr, 
char *dst) 
Parses a Tcl backslash sequence in src, storing the ensuing UTF-8 character 
in the string at ast. The variable pointed to by reaarer 1s updated to contain 
how many bytes of src were parsed. The number of bytes written to ast is 


returned. 


ant Tcl CommandComplete (const char *cmd) 


Returns i 1f cma holds one or more syntactically complete commands, o if the 
last command in cma is incomplete because of open braces or other faults. 


39.2 Dynamic Strings 


A dynamic string is a string that can be appended to without bound. As you 
append information to a dynamic string, Tcl automatically enlarges the 
memory area allocated for it as needed. If the string is short, Tcl avoids 
memory allocation altogether by using a small static buffer to hold the 
string. It also forms a convenient system for managing buffers dynamically, 
since it takes care of the low-level memory management details for you. Tcl 
provides 11 functions and macros for manipulating dynamic strings: 
* vcl_pDstringtnit Initializes a dynamic string to an empty string. Note that 
a dynamic string that has been initialized and not appended to does 
not need to be passed to ci _pstringrree. 
* Tcl _DStringAppena adds bytes to a dynamic string. The dynamic string 
remains null-terminated. 
® Tcl_DStringAppendElement adds a new list element to a dynamic string. 
® tcl DStringStartSublist @Nd tcl pstringzndsublist are used to create 
sublists within a dynamic string. 
* tcl_Dstringvalue returns the current value of a dynamic string. 
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* Tcl_DStringLength returns the current length of a dynamic string. 

* Tcl_DStringTrunc truncates a dynamic string. 

Tcl_DStringFree releases any storage allocated for a dynamic string and 

re-initializes the string. 

Tcl_DStringResult Moves the value of a dynamic string to the result for 
an interpreter and_ re-initializes the dynamic _ string. 
Tcl_DStringGetResult does the reverse operation, transferring the result 
to the dynamic string and resetting the interpreter. 

The following code uses several of these functions to implement a map 
command, which takes a list and generates a new list by applying some 
operation to each element of the original list. The map command takes two 
arguments: a list and a Tcl command. For each element in the list, it executes 
the given command with the list element appended as an additional 
argument. With the results of all the commands it generates a new list, and 
then returns this list as its result. Here are some examples of how you might 
use the map command: 


proc inc {x} {expr {$x + 1}} 


map {4 18 16 19 -7} inc 
=5: 29 JY 20 -6 
proc addz {x} {concat $x z} 
map {a b {a b c}} addz 
= ta 27 fbeZwk facbse gz} 


Here is a command function that implements nap: 
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int MapCmd(ClientData clientData, Tcl_Interp *interp, 
int argc, char *argv[]) { 
Tcl DString command, newList; 
int listArgc, i, result; 
char **listArgv; 


if (arge != 3) { 
Tcl SetResult(interp, "wrong # args", 
TCL_STATIC) ; 
return TCL ERROR; 
} 
if (Tcl _SplitList(interp, argv([1], &listArgce, 
&listArgv) != TCL_OK) { 
return TCL ERROR; 
} 
Tcl_DStringInit (&newList) ; 
Tcl DStringInit (&command) ; 
for (i=0 ; i<listArge ; i++) { 
Tcl DStringAppend(&command, argv[2], -1); 
Tel DStringAppendElement (&command, listArgv[i]}; 
result = Tcl_Eval(interp, 
Tcl _ DStringValue (&command) } ; 
Tcl _ DStringFree (&command) ; 
if (result != TCL_OK) { 
Tcl DStringFree(&newList) ; 
ckfree((char *) listArgv); 
return result; 
} 
Tcl DStringAppendBlement (&newList, 
Tcl _GetResult (interp) ) ; 
} 
Tcl DStringResult(interp, &newList) ; 
ckfree((char *) listArgv) ; 
return TCL OK; 


} 


Mapcma USES two dynamic strings. One holds the result list and the other holds 
the command to execute in each step. The first dynamic string is needed 
because the length of the command is unpredictable, and the second one is 
needed to store the result list as it builds up (this information cannot be kept 
immediately in the interpreter’s result because the result will be overwritten 
by the command that is evaluated to process the next list element). Each 
dynamic string is represented by a structure of type tc1_pstring. The structure 
holds information about the string, such as a pointer to its current value, a 
small array to use for small strings, and a length. Tcl does not allocate 
Tcl_DString Structures; it is up to you to allocate the structure (as a local 
variable, for example) and pass its address to the dynamic string library 
functions. You should never access the fields of a rci pstring structure 
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directly; use the macros and functions provided by Tcl. 

After checking its argument count, extracting all of the elements from the 
initial list, and initializing its dynamic strings, mapcma enters a loop to process 
the elements of the list. For each element, it first creates the command to 
execute for that element. It does this by calling rc1_pstringappena to append the 
part of the command provided in argv(21, then it calls tc1_pstringappendzlement 
to append the list element as an additional argument. These functions are 
similar in that both add new information to the dynamic string. However, 
Tcl DStringAppenad adds the information as raw text, whereas 
Tcl_DStringAppendElement Converts its string argument to a proper list element 
and adds that list element to the dynamic string (with a separator space, if 
needed). 

In this case, it is important to use tc1_pstringAppendziement for the list element 
so that it becomes a single word of the Tcl command under construction. If 
Tcl DStringAppend Were used instead and the element were a » c as in the 
example earlier in this section, the command passed to tci zvai would be 
addz a b c, Which would result in an error (because too many arguments are 
passed to the aaaz procedure). When tci_pstringappendziement 18 used, the 


command is adaz {a » c), Which parses correctly. 


1. There are other ways to invoke commands with extra arguments in a 
systematically correct way. For example, tci_newnistonj and the other list 
creation functions build a correctly quoted string that you can use with 
Tel _EvalobjEx, aNd ci Evalobjv allows the execution of a command without any 
parsing at all. 


Once mapcma has created the command to execute for an element, it invokes 
tcl Eval to evaluate the command. The tci_pstringrree call frees any memory 
allocated for the command string and resets the dynamic string to an empty 
value for use in the next command. If the command returns an error, mapcma 
returns that same error; otherwise, it uSeS tc1 pDstringAppendzlement to add the 
result of the command to the result list as a new element. 

mapema Calls tc pstringresuit after all of the list elements have been 
processed. This transfers the value of the string to the interpreter’s result in 
an efficient way (for example, it might transfer ownership of a dynamically 
allocated buffer to the interpreter instead of copying the buffer). 

Before returning, mapcma must free any memory allocated for the dynamic 
strings. It turns out that tc1_pstringrree has already done this for the command, 
and tc1_pstringresuit has done this for newnist. 

It is possible to implement much of mapcma more efficiently through the use of 
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the rc1_op; API. However, while that makes many parts of the processing 
more efficient, the actual dispatch mechanism mentioned (using a tc1_pstring) 
is still one of the simplest ways to achieve it. Indeed, the command might be 
written like this: 


int MapCmd(ClientData clientData, Tcl_Interp *interp, 
int objc, Tcl_Obj *const objv[]) { 
Tcl _DString command; 
int listObjc, i, result; 
Tcl _ Obj *newList, **listObjv; 


if (objec != 3) { 
Tcl _WrongNumArgs(interp, 1, objv, 
"list command") ; 
return TCL ERROR; 
} 
if (Tcl_ListObjGetElements(interp, objv[i], 
&listArgc, &listObjv) != TCL OK) { 
return TCL ERROR; 
} 
newList = Tcl_NewObj(); 
Tcl _DStringInit (&command) ; 
for (i=0 ; i<listObjc ; i++) { 
Tcl DStringAppend (&command, 
Tcl _GetString(objv[2]), -1); 


Tcl _ DStringAppendElement (&command, 
Tcl_GetString(listObjv[i])); 
result = Tcl_Eval(interp, 
Tel _ DStringValue (&command) ) ; 
Tcl _ DStringFree (&command) ; 
if (result != TCL_OK) { 
Tcl_DecrRefCount (newList) ; 
return result; 


} 


Tcl ListObjAppendElement (NULL, newList, 
Tcl _GetObjResult (interp)) ; 


} 


Tcl SetObjResult(interp, newList) ; 
return TCL OK; 


} 


As you can see, much of the code is extremely similar despite the 
differences in function names. 


39.3 String Matching 
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The functions tci_stringMatcn and tc1_stringcasematch (an extended version that 
allows control over whether matches are case-sensitive or not) provide the 
same functionality as the string match Tcl command. Given a string and a 
pattern, they return : if the string matches the pattern using glob-style 
matching and o otherwise. For example, here is a command function that 
USES Tcl_sStringMatch to implement a simplified version of isearcn that provides 
only glob-style matching. It returns the index of the first element in a list that 
matches a pattern, or -1 1f no element matches: 


int LsearchCmd(ClientData clientData, 
Tcl _Interp *interp, int objec, 
Tcl Obj *const objv[]) { 
char *pattern; 
int i, elemc; 
Tcl Obj **elemv; 
if (objec != 3) { 
Tcl_WrongNumArgs(interp, 1, objv, 
"list pattern"); 
return TCL ERROR; 
} 
if (Tcl ListObjGetElements(interp, objv[i], 
&elemc, &elemv) != TCL_OK) { 
return TCL ERROR; 


} 
pattern = Tcl _GetString(objv[2])}; 
for (i=0 ; i<elemc ; i++) { 
if (Tcl_StringMatch(Tcl_GetString(elemv[i]), 
pattern)) { 
Tcl SetObjResult(interp, Tcl NewIntObj(i)); 
return TCL OK; 
} 
} 


Tcl_SetObjResult(interp, Tcl_NewIntObj(-1)); 
return TCL OK; 


39.4 Regular Expression Matching 


When the simple matching capabilities of tci_stringmatch are insufficient, it is 
usually necessary to use regular expressions instead. Chapter 5 described 
the syntax and capabilities of regular expressions at the Tcl scripting level; 
this section describes Tcl’s C API for working with regular expressions. 
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The simplest functions to use for regular expression matching are 
Tol_RegExpMatch ANd tc1_RegExpMatchobj. These functions (which differ only in the 
types of their arguments) test whether a regular expression pattern matches a 
given string. They allow us to rewrite our previous simple tsearch-like 
example to use regular expressions like this: 


int RLsearchCmd(ClientData clientData, 

Tcl _Interp *interp, int objc, 
Tcl Obj *const objv{]) { 

Tcl _ Obj *pattern; 

int i, elemc, result; 

Tcl Obj **elemv; 

if (objec != 3) { 
Tcl WrongNumArgs(interp, 1, objv, "list pattern"); 
return TCL ERROR; 


if (Tcl_ListObjGetElements(interp, objv[il, 
&elemc, &elemv) != TCL_OK) { 
return TCL ERROR; 


} 
pattern = objv[2]; 
for (i=0 ; i<elemc ; i++) { 
result = Tcl RegExpMatchObj(interp, elemv[i], pattern); 
if (result == -1) { 
return TCL ERROR; 
} 
if (result == 1) { 
Tcl _ SetObjResult(interp, Tcl _NewIntObj(i)); 
return TCL OK; 
} 
} 


Tcl SetObjResult (interp, Tcl NewInt0Obj(-1)); 
return TCL OK; 


} 


The main additional complexity here is that the regular expression compiler 
can fail if presented with an invalid regular expression. When that is 
allowed for, the structure of the code that uses this is virtually identical to 
the version based on simple pattern matching. 

When additional complexity is required, such as when applying the regular 
expression efficiently to large numbers of strings or the same string multiple 
times to obtain all the locations within it that match, or accessing to the 
subexpressions that were matched, the more sophisticated variants of the 
regular expression API are used. The first level of sophistication allows the 
separation of the compilation and execution phases of regular expression 
matching through tc1_Regexpcompile aNd tc1_RegExpexec. These functions also 
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allow control over where in the string to start matching. They additionally 
enable the use of tc1_Rregrxprange to identify the substrings that match the 
subexpressions of the regular expression. 

A deeper level of sophistication is available as well. tc1_cetregrxprromop; 
allows control over the compilation flags used to generate a regular 
expression matcher, controlling things such as the regular expression dialect 
used or exactly how newlines within the string are processed. 
Tcl_RegExpExecobj allows control over not just the features that tc1_RegrxpExec 
does, but also over how many subexpressions are expected and whether the 
ends of strings should act as anchors. 1tc1_Regzxpcetinfo provides similar 
information tO tci_RegzxpRange, but in more detail and in a way better suited 
for use with the tc1_o»3; API. 


Note 


Be aware that when matching regular expressions, the 1c1_o»j-based 
APIs are considerably more efficient. This is because of the better 
treatment of caching afforded by the 1-1 on; system, and it is especially 
true when large numbers of expressions are used. However, when 
small numbers of patterns are used, the difference 1s not particularly 
great because the regular expression engine maintains an internal per- 
thread cache of compiled regular expressions. Also note that in 
virtually all cases, both literal string comparison and 1c1 stringmatch are 
more efficient when the thing being matched is something that they are 
capable of matching; regular expressions should be used only where 
their considerably greater power is required. 


39.5 Working with Character Encodings 


A character encoding is a mapping of characters and symbols used in 
written language into a binary format used by computers. Internally, Tcl 
represents strings in the Unicode encoding using the UTF-8 format. 
However, when you need to transfer a string to some other non-Tcl API, you 
may very well need to transform the string into a different encoding. For 
example, if you are passing a string to an operating system function, you 
need to send that string in the system encoding (often ISO 8859-1 in North 
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America, but quite different in other locales); without that, many characters 
(such as copyright marks, quotes, many currency symbols, etc.) get 
interpreted as multiple characters, often with a confounding accented letter 
apparently added. Chapter 5 described commands at the Tcl scripting level; 
this section describes Tcl’s C API for working with character encodings. 


Note 


Internally, Tcl represents zero bytes as a multibyte denormalized 
sequence because this allows UTF-8 strings to be processed correctly 
with normal C string utility functions. Note that only internal strings are 
represented this way; strings read from or presented to the outside 
world never use this encoding scheme. 


Tcl provides several functions for converting between Tcl’s UTF-8 
representation and the world of external encodings. tc1_vtftorxternalpstring 
takes a Tcl internal string and converts it to a string in some other encoding 
that is stored in a tci_pstring, and tc1_Externaltoutfpstring goes the other way. 
In order to use either of these functions, you need to get a handle for the 
encoding with 1c1 cetrncoding. Pass the special value wuiz instead of an 
encoding handle to use the system encoding (which 1s often the right thing to 
do, especially if using any operating system API). After using a handle for 
an encoding gotten with tc1_cetEncoding, always release that handle with 


Tcl FreeEncoding. 

For example, the following function togcma 1s an implementation of a Tel 
command that writes log messages to a POSIX syslog. After checking that 
the correct number of arguments has been supplied, it converts the supplied 
argument from Tcl’s internal encoding into the system encoding with 
Tcl _UtfToExternalDSstring and writes it to the log as an informational message. 
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int LogCmd(ClientData clientData, Tcl_Interp *interp, 
int objc, Tcl_Obj *const objv[]) { 
Tcl DString buffer; 
char *messageStr; 
if (objec != 2) { 
Tcl WrongNumArgs(interp, 1, objv, "message") ; 


return TCL ERROR; 


Tcl DStringInit (&buffer) ; 
messageStr = Tcl UtfToExternalDString (NULL, 


Tcl GetStringl(objv[1]), -1, &buffer); 
openlog("TclExample", 0, LOG USER); 
syslog(LOG_INFO, "ts", messageStr) ; 
closelog()}; 


Tcl DStringFree (&buffer) ; 
return TCL OK; 


The other functions for working with encodings are tc1_utfrozxternal and 
Tcl _Externaltoutt. These functions are focused on providing efficient support 
for streaming transformations; when converting whole strings, the 
Tcl_DString-based API is much more convenient. 

The most common case of having to work with encodings explicitly is when 
working with network sockets. This is because with the worldwide Internet, 
you cannot count on other parties to use the same encoding as you. Indeed, 
this is sufficiently important that all channels have their own encoding 
support, which means that as long as you configure the encoding upon them 
correctly, you do not explicitly need to manage the encoding. However, this 
can get distinctly complex with some protocols, especially those that mix 
different encoding schemes (for example, binary and a text encoding). 


39.6 Handling Unicode and UTF-8 Strings 


Though conceptually they use the same set of characters, Unicode strings 
(strictly, UCS-2 strings of host-system endian-ness) and UTF-8 strings have 
fundamentally different properties. In particular, Unicode strings can be 
indexed into at arbitrary offsets in constant time and so can have 
sophisticated operations applied to them rapidly, whereas UTF-8 strings are 
simple to pass through many traditional APIs. Tcl provides many functions 
for working with Unicode and UTF-8 strings. 

The functions tc1 unicharrovte and tcl_utfrounichar provide basic mapping 
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between Unicode and UTF-8 on a character-by-character basis. These are 
extended to working with whole strings of Unicode and UTF-8 characters 
by the functions tc1_ unichartoutfpstring and tc1_vtfTounicharpstring, Which both 
target a buffer in a tc1_pstring. 

Tcl also provides analogs of many of the C string functions; Table 39.1 
shows the mapping of C string functions to analogous Tcl functions. 
Tcl_StringCasematch, Which handles UTF-8 strings, also has a Unicode string 


analog: Tcl _UniCharCaseMatch. 


Table 39.1 Tcl Unicode and UTF-8 Analogs of C String Functions 


C string function Unicode string analog UTF-8 string analog 
strlen Tel _UniCharLen Tcl NumUtfChars 
strncmp [cl UniCharNemp Tcl UtfNemp 
strncasecmp Tcl UniCharNcasecmp Tel UtfNcasecmp 


strchr Tol UtfFindFirst 


strrchr Tcl UtfFindLast 


In addition, the functions ci _vtrnext and rci_utfPrev are used to step forward 
and backward through a UTF-8-encoded string, and 1c1_unicharatindex and 
Tcl_UtfatIndex respectively allow looking up a character at a specific index of 
a Unicode or UTF-8 string, returning the Unicode character at that location 
or a pointer to that location respectively. 

When processing a buffer that might contain partial UTF-8 characters, the 
function tci_utfcharcomplete returns whether the string its argument points to 
contains at least one complete UTF-8 character. This is useful because many 
protocols require that only complete characters be transferred in any 
message. 

Finally, tci_utfpacksiash provides a parser for the backslash sequences 
supported by Tcl. It copies a backslash sequence from a source buffer to a 
target buffer, transforming it in the process to the character that it maps to 
according to Tcl’s syntax rules and returning the number of bytes written into 
the target buffer in the process. 

The C function that follows illustrates how to use these together. It takes a 
character and a pointer to a UTF-8 string and returns a new string that 
consists of that character and the two characters on either side of it. This 
could be implemented using the Tcl script 


set i [string first $ch $string] expr 
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{$i<0 ? '" : [string range $string $1-2 $i+2]} 


and is a simple application of strchr with ASCII strings, but it is a little 
more complex with UTF-8 because characters are not a constant width. 


char *SubstringAbout (int ch, const char *string) { 
const char *end, *1loc; 
char *buf; 
int i; 


/* Pind the character. */ 


loc = end = Tcl_UtfFindFirst (string, ch); 
if (loc == NULL) { 
return NULL; 


/* Find one char past the end of the area. */ 
for (i=0; *end!='\0' && i<3; i++) { 
end = Tcl UtfNext (end) ; 


/* Find the start of the area. */ 
for (1=0; i<2; i++) { 

loc = Tcl_UtfPrev(loc, string); 
} 


/* Copy and return the substring. */ 
buf = ckalloc( (end-loc) +1); 

memcpy (buf, loc, end-loc); 

buf fend-loc] = '\0'; 

return buf; 


Note 


Though the result string of the supstringabout function is only up to five 
characters long, those five characters could take as many as 15 bytes, 
depending on the writing system used. In the future, it could be even 
longer as the space of Unicode characters outside the Basic 
Multilingual Plane gets defined and supported. But since this function 
makes no assumptions about the actual length of the result string, it will 
continue to function correctly when this happens. 


39.7 Command Completeness 
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When an application reads commands typed interactively, it must wait until 
a complete command has been entered before evaluating it. For example, 
suppose an application is reading commands from standard input and the 
user types the following three lines: 


foreach i {1 23 4 5} { 
puts "Si*$i is [expr $i*Si]" 
} 


If the application reads each line separately and passes it to 1c1_svai, the first 
line will generate a “missing close brace” error. Instead, the application 
should collect input until all the commands read are complete (for example, 
there are no unmatched braces or quotes), then execute all of the input as a 
single script. The function tc1_commandcompiete Makes this possible. It takes a 
string as argument and returns : if the string contains syntactically complete 
commands or o if the last command is not yet complete. 

The C function that follows uses dynamic strings and 1c1_commandcomplete to 
read and evaluate a command typed on standard input. (For clarity, it avoids 
using the Tcl channel API. Otherwise, this code would be longer and would 
obscure the parts of the function that are really being demonstrated.) It 
collects input until all the commands read are complete, and then it 
evaluates the command(s) and returns the completion code from the 
evaluation. It uses tc1 Recordandzval to evaluate the command so that the 
command is recorded on the history list. 


int DoOneCmd(Tcl_ Interp *interp) { 


char line[200] ; 
Tel DString cmd; 
int code; 
Tcl DStringInit (&cmd) ; 
while (1) { 
if (fgets(line, 200, stdin) == NULL) { 
break; 
} 
Tcl DStringAppend(&cmd, line, 
if (Tcl_CommandComplete(Tcl_DStringValue(&cmd))) { 
break; 
} 
} 


code = Tcl_RecordAndEval (interp, 
Tcl DStringValue(&cmd), 0); 

Tcl DStringFree (&cmd) ; 

return code; 


749 


In the foreach example, doonecma Will collect all three lines before evaluating 
them. If an end of file occurs, ¢gets will return wort, and doonecma Will evaluate 
the command if it is not yet complete. 

Tcl _Commandcomplete Checks for completeness only in the sense of parsing 
correctly. It does not guarantee that the script will behave correctly. For 
example, if a user accidentally splits a command like set x y over two lines 
by typing a newline after the x, each line will be considered to be complete. 
The first line will simply query the variable instead of modifying it, and the 
second line will invoke a command y, which will probably generate an 
error. 
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40. Hash Tables 


A hash table is a collection of entries, where each entry consists of a key 
and a value. No two entries may have the same key. Given a key, a hash 
table can locate its entry very quickly and hence the associated value. Tcl 
contains a general-purpose hash table package that it uses in several places 
internally. For example, all of the commands in an interpreter are stored ina 
hash table where the key for each entry is a command name and the value is 
a pointer to information about the command. All of the variables in a 
namespace are stored in another hash table where the key for each entry is 
the name of a variable and the value is a pointer to information about the 
variable. 

Tcl exports its hash table facilities through a set of library functions so that 
applications can use them, too. The most common use for hash tables is to 
associate names with objects. In order for an application to implement a 
new kind of object, it must give the objects textual names for use in Tcl 
commands. When a command function receives an object name as an 
argument, it must locate the C data structure for the object. Typically there is 
one hash table for each type of object, where the key for an entry is an 
object name and the value is a pointer to the C data structure that represents 
the object. When a command function needs to find an object, it looks up its 
name in the hash table. If there is no entry for the name, the command 
function returns an error. 

The examples in this chapter use a hypothetical application that implements 
objects called “gizmos.” Each gizmo is represented internally with a 
structure declared like this: 


typedef struct Gizmo { 
. fields of gizmo object ... 
} Gizmo; 


The application uses names like gizmoa2 to refer to gizmos in Tcl commands, 
where each gizmo has a different number at the end of its name. The 
application follows the action-oriented approach described in Section 30.3 
by providing a collection of Tcl commands to manipulate the objects, such 
AS gizmo::create to create a New gIZMO, gizmo::delete to delete an existing 
GIZMO, gizmo::search to find gizmos with certain characteristics, and so on. 
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40.1 Functions Presented in This Chapter 


This chapter discusses the following functions for creating and manipulating 
hash tables: 

® void Tcl_InitHashTable(Tcl_ HashTable *tablePtr, 

int keyType) 

Creates a new hash table and stores information about the table at tavierer. 
keyType 18 ether tcL_sTRING KEYS, TCL ONE WORD KEYS, OF an integer greater than 1. 

* Tcl_InitObjHashTable(Tcl_ HashTable tablePtr) 
Creates a new hash table and stores information about the table at «tapierer. 
The keys in the hash table are 1tc1 o»j* references (cast to char«), with key 
equality determined according to whether the string representations of keys 
(as returned by rc1 cetstring) are the same. Note that this is a front end to 
Tcl_InitCustomHashTable, Where the type of the keys is defined to be a managed 
reference to a tc1_ 0b}. 


® Tcl InitCustomHashTable (Tcl HashTable *tablePtr, 


int keyType, Tcl_HashKeyType *typePtr) 

Creates a new hash table and stores information about the table at eapierer. 
The = keyrype argument Should be one of cct custom type Keys OF 
TCL_custom ptr xeys, and the actual type of the keys should be more completely 
described by the typerer argument, which must be a pointer to a static 
structure containing a key type descriptor. See the reference documentation 
for a complete description of key type descriptors and how to use this 
function. 

* void Tcl DeleteHashTable (Tcl HashTable *tablePtr) 
Deletes all the entries in the hash table and frees up related storage. 


© Tcl HashEntry *Tcl CreateHashEntry ( 


Tcl _HashTable *tablePtr, char *key, int *newPtr) 
Returns a pointer to the entry in tapiertr whose key is xey, creating a new 
entry if needed. newrtr is set to 1 1f a new entry was created or o if the entry 
already existed. 


* Tcl HashEntry *Tcl_ FindHashEntry (Tcl HashTable *tablePtr, 


char *key) 
Returns a pointer to the entry in tapierer whose key 1s xey, or nut 1f no such 
entry exists. 


* void Tcl DeleteHashEntry (Tcl HashEntry *entryPtr) 
Deletes an entry from its hash table. 

* ClientData Tcl GetHashValue(Tcl_ HashEntry *entryPtr) 
Returns the value associated with a hash table entry. 
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® void Tcl SetHashValue (Tcl HashEntry *entryPtr, 


ClientData value) 
Sets the value associated with a hash table entry. 


® char *Tcl_ GetHashKey(Tcl HashTable *tablePtr, 


Tcl HashEntry *entryPtr) 
Returns the key associated with a hash table entry. 


bd Tcl HashEntry *Tcl_ FirstHashEntry(Tcl HashTable *tablePtr, 


Tcl HashSearch *searchPtr) 
Starts a search through all the elements of a hash table. Stores information 
about the search at searcher and returns the hash table’s first entry or wotz if it 
has no entries. 


- Tcl HashEntry *Tcl NextHashEntry ( 


Tcl HashSearch *searchPtr) 
Returns the next entry in the search identified by searcnrer or nuit if all entries 
in the table have been returned. 
® char *Tcl_ HashStats (Tcl HashTable *tablePtr) 
Returns a string giving usage statistics for tabiertr. The string is dynamically 
allocated and must be freed by the caller. 


40.2 Keys and Values 


Tcl hash tables support four different kinds of keys. All of the entries in a 
single hash table must use the same kind of key, but different tables may use 
different kinds. The most common form of key is a string. In this case each 
key is a null-terminated string of arbitrary length, such as gizmois OF waste not 
want not. Different entries in a table may have keys of different length. The 
gizmo implementation uses strings as keys. 

The second form of key is a one-word value. In this case each key may be 
any value that fits in a single word, such as an integer. One-word keys are 
passed into Tcl using values of type cnar *, so the keys are limited to the size 
of a character pointer. 

The third form of key is an array. In this case each key is an array of integers 
(C int type). All keys in the table must be the same size. 

The last form of key is a reference to a 1c1 op; instance. In this case, each 
key is a pointer to a rc1_o»j, and the hash table retains a reference to each 
unique key value. 1c1_o»j+ keys are passed into the hashing engine by casting 
them to char* and are compared by comparing their string representations (as 
returned by tci_cetstringFromob}). 

The values for hash table entries are items of type ciientpata, which are large 
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enough to hold either an integer or a pointer. In most applications, such as 
the gizmo example, hash table values are pointers to records for objects. 
These pointers are cast into ciientpata 1tems when stored in hash table 
entries, and they are cast back from ciientpata to object pointers when 
retrieved from the hash table. 


40.3 Creating and Deleting Hash Tables 


Each hash table is represented by a C structure of type tc1_Hasntabie. The 
client, not Tcl, allocates space for such structures, which are usually global 
variables or elements of other structures. When calling hash table functions, 
you provide a pointer to a tc1_Hashtabie Structure as a token for the hash table. 
You should not use or modify any of the fields of a rc1_sasnrabie directly. Use 
the Tcl library functions for this. 

Here is how a hash table might be created for the gizmo application: 


Tcl HashTable gizmoTable; 


Tcl InitHashTable(&gizmoTable, TCL STRING KEYS) ; 


The first argument to rci_tnitHashTable IS @ Tcl_HashTable pointer, and the second 
argument is an integer that specifies the sort of keys that will be used for the 
table. tct_strinc_xevs means that strings will be used as the keys for the table. 
If rct_onz_worp xevs 1S Specified, it means that single-word values such as 
integers or pointers will be used as keys. If the second argument is neither 
TCL_STRING KEYS NOY TcL_onz_worp xeys, It must be an integer value greater than 1; 
this means that keys are arrays with the given number of ints in each array. 
Tcl _InitHashTable Initializes the structure to refer to an empty hash table with 
keys as specified. (The additional flag values rect custom tvez xevs and 
TCL_CUSTOM_PTR_ KEYS May be used only with Tcl_InitCustomHashTable.) 

Hash tables whose keys are ‘ci op; references are created with 
Tcl_InitobjHashTable, Whose only argument Is a tcl Hashtable pointer, just as 
with the first argument to tc1_titHashTable. 

Tcl DeleteHashTable Temoves all the entries from a hash table and frees the 
memory that was allocated for the entries and the table (except space for the 
Tcl_HashTable Structure itself, which is the property of the client calling 
Tcl _DeleteHashTable). For example, the following statement could be used to 
delete the hash table we just initialized: 


Tcl_DeleteHashTable(&gizmoTable); 
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40.4 Creating Entries 


The function tc1 createHashentry creates an entry with a given key, and 
Tcl_SetHashvalue Sets the value associated with the entry. For example, the 
following code might be used to implement the gizmo: :create command, which 
makes a new gizmo object: 


int GizmoCreateCmd(ClientData clientData, 
Tcl Interp *interp, int argc, char *argv[]) { 
static unsigned int id = 1; 
int new; 
Tcl HashEntry *entryPtr; 
Gizmo *gizmoPtr; 
char nameBuf[5 + TCL _INTEGER_SPACE] ; 


check argc, etc. 


do { 
sprintf (nameBuf, "gizmotu", id); 
id++; 
entryPtr = Tcl_CreateHashEntry(&gizmoTable, 
nameBuf, &new) ; 
} while (!new); 


gizmoPtr = (Gizmo *) ckalloc(sizeof (Gizmo) ); 
Tcl SetHashValue(entryPtr, gizmoPtr} ; 


initialize *gizmoPtr, etc. 


Tcl SetResult(interp, nameBuf, TCL VOLATILE) ; 
return TCL OK; 


} 


This code creates a name for the object by concatenating gizmo with the value 
of the static variable ia. It returns the name of the new object as the result of 
the Tcl command, but during creation it uses a stack-local buffer, namesur, to 
hold the name. cizmocreatecma then increments ia so that each new object will 
have a unique name; in thread-safe code this would have to be either 
protected with a mutex or made into either an interpreter- or thread-local 
variable. tci_createnashrntry 1S called to create a new entry with a key equal 
to the object’s name; it returns a token for the entry. Under normal conditions 
an entry with the given key will not already exist, in which case 
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Tcl _CreateHashEntry S@tS new to 1 to indicate that it created a new entry. 
However, it is possible for tci createHasnzntry to be called with a key that 
already exists in the table. In cizmocreatecma this can happen only if a very 
large number of objects are created, so that ia wraps around to zero again. If 
this happens, tci_createHashEntry S€tS new tO 0; Gizmocreatecma Will try again with 
the next larger ia until it eventually finds a name that isn’t already in use. 
After creating the hash table entry, cizmocreatecma allocates memory for the 
object’s record and invokes 1c1_setHasnvalue to store the record address as the 
value of the hash table entry. The first argument to 1c1_setHasnvalue 18 a token 
for a hash table entry, and its second argument, the new value for the entry, 
can be anything that fits in the space of a ciientpata value. After setting the 
value of the hash table entry, cizmocreatecma Initializes the new object’s record 
and stores the name of the object (in namesur) in the interpreter’s result. 


Note 


Tcl’s hash tables restructure themselves as you add entries. A table 
does not use much memory for the hash buckets when it has only a 
small number of entries, but it will increase the size of the bucket array 
as the number of entries increases. Tcl’s hash tables operate efficiently 
even when they have a very large number of entries. 


When working with tc1_o»j keys, the hash table system manages the lifetime 
of the keys for you. The only constraint is that the object argument to 
Tcl _CreateHashEntry Must be cast to a char+ to ensure that the type signature is 
correctly obeyed. Once you have obtained a vc1 Hashentry pointer from an 
object hash table, you use it identically to the one from a string hash table; 
hash tables do not constrain the types of their values at all. 


40.5 Finding Existing Entries 


The function tci_rinaashzntry locates an existing entry in a hash table. It is 
similar to tci_createHashzntry except that 1t does not create a new entry if the 
key doesn’t exist in the hash table. tci_rinaasnzntry 18 typically used to find 
an object, given its name. For example, the gizmo implementation might 
contain a utility function called cetcizmo, which is something like 1ci_cetint 
except that it translates its string argument to a cizmo pointer instead of an 
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integer: 


Gizmo *GetGizmo(Tcl Interp *interp, char *string) { 
Tcl _HashEntry *entryPtr; 
entryPtr = Tcl FindHashEntry(&gizmoTable, string) ; 


if (entryPtr == NULL) { 
Tcl _AppendResult(interp, "no gizmo named \"", 
string, "\"", NULL); 


return NULL; 


} 


return (Gizmo *) Tcl_GetHashValue(entryPtr} ; 


} 


GetGizmo looks up a gizmo name in the gizmo hash table. If the name exists, 
GetGizmo extracts the value from the entry using 1c1_cetHashvalue, converts it to a 
Gizmo pointer, and returns it. If the name doesn’t exist, cetcizmo stores an error 
message in the interpreter’s result and returns nui. This is the same when 
working with a 1c1_o»j* hash table, except the key must be cast to char+ before 
itis put into tc1_FinaHashEntry. 

GetGizmo can be invoked from any command function that needs to look up a 
gizmo object. For example, suppose there is a command gizmo::twist that 
performs a “twist” operation on gizmos, and that it takes a gizmo name as its 
first argument. The command might be implemented like this: 


int GizmoTwistCmd(ClientData clientData, 
Tcl_Interp *interp, int argc, char *argv[]) { 
Gizmo *gizmoPtr; 
check argc, etc. 
gizmoPtr = GetGizmo(interp, argv[l1]); 
if (gizmoPtr == NULL) { 
return TCL ERROR; 
} 
. perform twist operation 
return TCL OK; 


40.6 Searching 


Tcl provides two functions that you can use to search through all of the 
entries in a hash table. rci rirstHashzntry Starts a search and returns the first 
entry, and tc1 NextHashzntry returns successive entries until the search is 
complete. For example, suppose you wish to provide a gizmo::search 
command that searches through all existing gizmos and returns a list of the 
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names of the gizmos that meet a certain set of criteria. 
be implemented as follows: 


int GizmoSearchCmd(ClientData clientData, 


This command might 


Tcl_Interp *interp, int argc, char *argv[]) { 


Tcl _HashEntry *entryPtr; 
Tcl_HashSearch search; 
Gizmo *gizmoPtr; 


. process arguments to choose search criteria 
for (entryPtr = Tcl_FirstHashEntry(&gizmoTable, &search) ; 


entryPtr != NULL; 
entryPtr = Tcl_NextHashEntry(&search)) { 
gizmoPtr = (Gizmo *) Tcl _GetHashValue(entryPtr) ; 


ct 
if (...object satisfies search criteria...) { 


Tcl_AppendElement (interp, 


Tcl_GetHashKey (&gizmoTable, entryPtr)); 


} 


P| 


} 


return TCL OK; 


} 


A structure of type tci_Hashsearch 18 used to keep trac 


k of the search; it is 


possible to carry out multiple searches simultaneously, using a different 


Tcl_HashSearch Structure for each. tc1 rirstHashEntry Initializes this structure and 
returns a token for the first entry in the table (or wuz 1f the table 1s empty). 
Tcl_NextHashEntry uses the information in the structure to step through 


successive entries in the table; each call to rci_nextHasnentry returns a pointer 
to the next entry (in no particular order), and nuit is returned when the end of 


the table is reached. cizmosearcncma extracts the val 


ue from each entry, 


converts it to a cizmo pointer, and checks whether that object meets the 


criteria specified in the command’s arguments. If so, 
Tcl_GetHashkey function to get the name of the object (i.e 


GizmoSearchcma uses the 
., the entry’s key) and 


invokes rci_appendzlement to append the name to the interpreter’s result as a 
list element. Though the type of the result of tc1_cetasnkey 1S char*, its actual 
type depends on the key type configured at hash table creation time. 


Note 


It is not safe to modify the structure of a hash table during a search 


except to delete the current entry returned by 


Tcl FirstHashEntry and 


Tcl_NextHashentry. If you create any entries or delete any entry other than 
the current one, you should terminate any searches of that table that are 
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in progress. 


40.7 Deleting Entries 


The function 1ci_peletenashentry deletes an entry from a hash table. For 
example, the following function uses tc1_peleteHashzntry to implement a 


gizmo::delete Command, which takes any number of arguments 
gizmo objects they name: 


int GizmoDeleteCmd(ClientData clientData, 


and deletes the 


Tcl_Interp *interp, int argc, char *argv[]) { 


Tcl_HashEntry *entryPtr; 
Gizmo *gizmoPtr; 

int i; 

for (i = 1; i < argc; i++) { 


entryPtr = Tcl _FindHashEntry (&gizmoTable, argv[i]); 


if (entryPtr == NULL) { 
continue; 
} 


gizmoPtr = (Gizmo *) Tcl GetHashValue(entryPtr) ; 


Tcl DeleteHashEntry(entryPtr) ; 
clean up *gizmoPtr . 
ckfree((char *) gizmoPtr) ; 


} 


return TCL OK; 


} 


GizmoDeletecma Checks each of its arguments to see if it is the name of a gizmo 


object. If not, the argument is ignored. Otherwise, cizmope1e 


recma eXtracts a 


Gizmo pointer from the hash table entry and calls rci_peietenasnentry to remove 
the entry from the hash table. Then it performs internal cleanup on the gizmo 


object if needed and frees the object’s record. 


Note 


Tcl does not manage the lifetime of the hash values for you. If they are 


values that need explicit freeing, you should do this 


when you use 


Tcl_DeleteHashEntry OF Tcl_DeleteHashTable, Or the memory is leaked. 
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40.8 Statistics 


The function vci sasnstats returns a string containing various statistics about 
the structure of a hash table. For example, it might be used to implement a 
gizmo::stat Command for gizmos: 


int GizmoStatCmd(ClientData clientData, Tcl_Interp *interp, 
int argc, char *argv[]) { 
if (arge != 1) { 
Tcl _ SetResult(interp, "wrong # args", TCL STATIC); 
return TCL ERROR; 


} 


Tcl_SetResult(interp, Tcl _HashStats(&gizmoTable), TCL DYNAMIC) ; 
return TCL OK; 


} 


The string returned by tci_nashstats 18 dynamically allocated and must be 
passed to ckfree OF Tcl_Free} Gizmostatcma USeS this string to set the interpreter’s 
result using the tci_setresuit command with the lifetime mode set to 
TCL DYNAMIC. 

The string returned by rci_nasnstats 18 not formally defined, but it contains 
human-readable information such as the following: 


1416 entries in table, 1024 buckets 
number of buckets with entries: 60 
number of buckets with entries: 591 
number of buckets with entries: 302 
number of buckets with entries: 67 
number of buckets with entries: 5 


number of buckets with entries: 0 
number of buckets with entries: 0 
number of buckets with entries: 0 
number of buckets with entries: 0 


wows nur WN HY OS 


number of buckets with entries: 0 
number of buckets with more than 10 entries: 0 
average search distance for entry: 1.4 


You can use this information to see how efficiently the entries are stored in 
the hash table. For example, the last line indicates the average number of 
entries that Tcl will have to check during hash table lookups, assuming that 
all entries are accessed with equal probability. 
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41. List and Dictionary Objects 


As of version 8.5, Tcl provides two data structures that are easily 
accessible from both C and Tcl: lists and dictionaries. Manipulating lists at 
the Tcl scripting level is covered in Chapter 6 and dictionaries in Chapter _7. 
The current Tcl list API has been around for several years, so you can count 
on its being present in any reasonably up-to-date Tcl installation. On the 
other hand, dictionaries (which are based internally on the hash tables 
discussed in Chapter 40) require Tcl 8.5 or later. 


41.1 Functions Presented in This Chapter 


This chapter discusses the following functions for manipulating lists and 
dictionaries: 

* Tcl Obj *Tcl_ NewListObj (int objc, Tcl Obj *CONST objv[]) 
Creates a new list object from an array ovjv pointing to Tcl objects and the 
number of objects to use, onjc. 


® int Tcl _ListObjAppendElement (Tcl Interp *interp, 
Tcl Obj *listPtr, Tcl Obj *objPtr) 
Given a pointer 1istr¢r to an object containing a list, appends o»jr¢r to the 
list. 


® int Tcl ListObjAppendList (Tcl _Interp *interp, 


Tcl Obj *listPtr, Tcl Obj *elemListPtr) 
Given a pointer iistrer to an object containing a list (or that can be 
converted to one), appends a second list ciemzistrtr tO 1istPtr. 
® Tcl SetListObj (Tcl Obj *objPtr, int objc, 
Tcl Obj *CONST objv[]) 
Sets the list object opjrer to contain onj- elements contained 1N on3v. 


e aint Tcl ListObjGetElements (Tcl Interp *interp, 


Tcl Obj *listPtr, int *objcPtr, 


Tcl Obj ***objvPtr) 
Returns a count and a pointer to an array of the elements in a list object. 
® int Tcl ListObjIndex(Tcl_Interp *interp, 
Tel Obj *listPtr, int index, Tcl_Obj **objPtrPtr) 
Given a pointer, 1istrer, to an object containing a list, places the object at 


index index IN objrerrtr. If inaex 18 Out of range (-1, or greater than the index of 
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the last element), nuxz is stored in opjrtreer and rci._ox 1s returned. 


* int Tcl ListObjLength(Tcl_ Interp *interp, 


Tcl Obj *listPtr, int *intPtr) 
Given a pointer 1istrer to an object containing a list, places the list’s length 
IN intper. 
° 


int Tcl ListObjReplace(Tcl_ Interp *interp, 


Tcl Obj *listPtr, int first, int count, int objc, 


Tcl Obj *CONST objv[]) 
Deletes count elements from iisterr, starting with the element indexed by 
first, and then replaces them with o»j- number of elements from the onjv 
array Of rc1_o»j$, Starting with the first element. If onjv is nor, no new 
elements are added. If the argument first is 0 or negative, it refers to the first 
element. If rirse is greater than or equal to the number of elements in the list, 
no elements are deleted; the new elements are appended to the list. count 
gives the number of elements to replace. If count 1s 0 or negative, no elements 
are deleted; the new elements are simply inserted before the one designated 
by first. 

® Tcl Obj *Tcl_NewDictObj () 
Creates a new, empty dictionary object. 

* int Tcl DictObjPut(Tcl_Interp *interp, 


Tcl Obj *dictPtr, Tcl _ Obj *keyPtr, 


Tcl Obj *valuePtr) 
Adds a key-value pair to a dictionary, or updates the value for a key if that 
key already has a mapping in the dictionary. 

* int Tcl DictObjPutKeyList (Tcl _Interp *interp, 


Tcl Obj *dictPtr, int keyc, const Tcl Obj *keyv, 


Tcl Obj *valuePtr) 
Adds a key-value pair to a nested dictionary, or updates the value for a key 
if that key already has a mapping in the dictionary. The xeyv argument 
specifies a list of keys (with outermost keys first) that acts as a path to the 
key-value pair to be affected. Nested dictionaries are created for 
nonterminal keys where they do not already exist. 

® int Tcl DictObjGet(Tcl_Interp *interp, 


Tcl Obj *dictPtr, Tcl Obj *keyPtr, 


Tcl Obj **valuePtrPtr) 
Given a key, gets its value from the dictionary (or wuz 1f the key is not found 
in the dictionary). 
* int Tcl DictObjRemove (Tcl Interp *interp, 
Tcl Obj *dictPtr, Tcl Obj *keyPtr) 


Removes the key/value pair with the given key from the dictionary; the key 
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does not need to be present in the dictionary. 
* int Tcl _DictObjRemoveKeyList (Tcl Interp *interp, 
Tcl Obj *dictPtr, int keyc, const Tcl Obj *keyv) 
Removes a key-value pair from a nested dictionary. The xeyy argument 
specifies a list of keys (with outermost keys first) that acts as a path to the 
key-value pair to be affected. All nonterminal keys must exist and have 
dictionaries as their values. 
* int Tcl DictObjSize(Tcl_Interp *interp, 
Tel Obj *dictPtr, int *sizePtr) 
For the given dictionary, stores in the sizerer variable a count of the number 
of key-value pairs. 
° 


int Tcl DictObjFirst(Tcl_Interp *interp, 


Tcl Obj *dictPtr, Tcl DictSearch *searchPtr, 


Tcl Obj **keyPtrPtr, Tcl Obj **valuePtrPtr, 

int *donePtr) 
Commences an iteration across all the key-value pairs in the given 
dictionary, placing the key and value in the variables pointed to by the 
keyptrptr ANd valuertretr arguments. Locks the dictionary to enable safe 
iteration over the dictionary. Stores a search token in the variable pointed to 
by searcnptr. Stores o in the variable pointed to by aonerer if there are 
additional key-value pairs to process, or nonzero if the iteration is 
complete. 

® void Tcl DictObjNext (Tcl DictSearch *searchPtr, 

Tcl Obj *keyPtrPtr, Tcl Obj **valuePtrPtr, 

int *donePtr) 
Given a search token, retrieves the next key-value pair in a dictionary, 
placing the key and value in the variables pointed to by the keyrerper and 
valueptretr arguments. Stores o in the variable pointed to by aonerer if there 
are additional key-value pairs to process, or nonzero if the iteration is 
complete. 

* void Tcl DictObjDone (Tcl DictSearch *searchPtr) 

Given a search token, terminates a dictionary iteration before you reach the 
end of the dictionary and unlocks the dictionary. You don’t need to call 
Tcl_DictObjDone If a previous call to 1c1_pictopjFirst OF Tcl _Dictobjnext Indicates 
that the iteration has terminated. It is safe to call tc1 pictobjpone multiple 
times with the same search token. 


41.2 Lists 
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Lists are implemented internally as position-indexed C arrays (rather than 
linked lists or Tcl arrays), so operations on them are generally very fast. 
The list C API supports the same basic operations that the Tcl list 
commands do: creating lists; adding elements to lists; combining lists; 
getting, setting, and replacing list elements; as well as finding the length of 
the list. 

Like other object types, lists have a function, 1c1 Newnistonj, that creates a 
new, empty Tcl object, as in the following example: 


Tcl Obj *listobj, strobj, intobj; 

listobj = Tcl_NewListObj(0, NULL); 

strobj = Tcl NewStringObj ("Answer", -1); 

intobj = Tcl NewIntObj (42) ; 

Tcl ListObjAppendElement (interp, listobj, strobj); 
Tcl_ListObjAppendElement (interp, listobj, intobj); 


In this example, we first create an empty list. Then we add two elements to 
it using the 1c1_tistobjappendzlement function. It is not necessary to increase the 
reference count of the intovj and stropj Objects; rc1_ListobjaAppendzlement takes 
care of doing that because the objects have at least one reference to them 
while associated with the list. You can also take one list object and extend it 
with the elements of another list object by using the tc1_istobjappenatist 
function. 

Section 30.4 of the chapter on design philosophy discussed the use of a 
tagged list, such as max 105 min 89 average 96, aS a means of passing 
information between Tel and C. Such a list is useful in and of itself, because 
it describes the data. Furthermore, it could also be passed to the array set 
command in order to create an array: 


array set temps {max 105 min 89 average 96} 


Building this array from C is easy when tc1_nistopjappendzlement, aS in the first 
example, is used to build up the list piece by piece. Another approach is to 
use an array Of rc1_o»j pointers, where each 1c1_ on; 1s intended as an element 
in the resulting list, and pass the array to tci_Newtistooj along with a count of 
the number of objects: 
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Tcl Obj *templist; 
Tcl_ Obj *objs([6]; 
min = 89; 

max = 105; 

average = 96; 


objs(0) = Tcl_NewStringObj ("max", -1); 
objs[{1] = Tcl_NewIntObj (max) ; 

objs[(2] = Tcl_NewStringObj ("min", -1); 
objs[3] = Tcl_NewIntObj (min) ; 

objs(4] = Tcl_NewStringObj ("average", -1); 


objs[(5] = Tcl_NewIntObj (average) ; 
templist = Tcl NewListObj(6, objs); 
Tcl_IncrRefCount (templist) ; 


It’s also possible to start with an object not originally created as a list 
object and do list operations on it. As long as the string representation of the 
object is that of a well-formed Tcl list, the accessor functions can convert 
the object for use with the list functions. If the object does not have a valid 
list structure, the accessor functions return tc. zrror. For example, the 
following code first builds a tc1_o5; based on a string. The subsequent list 
operations then convert the object to have a list representation: 


int objnum = 0; 

int listlength = 0; 

Tcl_Obj *element; 

Tcl Obj *mylist = Tcl NewStringObj("a bcd", -1); 
Tcl _ Obj **objs; 


Tcl _ListObjIndex(interp, mylist, 1, &element) ; 
Tcl ListObjGetElements(interp, mylist, &objnum, &objs) ; 
Tcl_ListObjLength(interp, mylist, &listlength) ; 


The tci_tistobjindex returns an object representing the second element of the 
list, in this case », and places the result in eiement. tcl _ListopjGetElements 
retrieves all of the list elements as an array of 1ci_o»js and stores a pointer 
to the array in objs and a count of the elements in objnun. The tc1_opj array 
pointed to 1s managed by Tcl and should not be freed or written to by the 
caller. The final example stores a count of the list elements in the variable 
listlength. 

The tci_nistobjreplace function can perform both element insertion and 
deletion and so serves as the basis of many list operations. Its arguments in 
order are the Tcl interpreter, a pointer to a list object to process, the index 
of the first element to delete, a count of the number of consecutive elements 
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to delete, the count of the number of elements to insert in their place, and an 
array Of tc1_ovjs that serve as replacement elements. Any element deleted 
from the list has its rc1 op; reference count decremented automatically, and 
any element added to the list has its tc1 o»; reference count incremented 
automatically. 

For example, the following replaces the single element at index 3 with a 
single new element: 


Tcel_Obj *newObj = Tcl_ NewStringObj("Carol", -1); 
Tel ListObjReplace(interp, mylist, 2, 1, 1, &newOb)j); 


This example, on the other hand, inserts a new element at the beginning of 
the list: 


Tel_Obj *newObj = Tcl NewStringObj("Dean", -1); 
Tcl _ListObjReplace(interp, mylist, 0, 0, 1, &newOb)j); 


Naturally, lists can also contain other list objects, which allows us to nest 
lists within lists, or dictionaries within lists, or lists within dictionaries, and 
so on. However, be careful not to create a structure that 1s so complex that it 
is difficult for someone else to understand how it works, or for you to 
understand if you have to revisit your program later—if you have a list of 
lists of dictionaries, perhaps it’s time to review your code! 


41.3 Dictionaries 


Dictionaries, as we have seen for Tcl, are a mapping of values to unique 
keys. From the scripting perspective, the values can be any string, which 
means that they can be interpreted as lists or nested dictionaries. Internally, 
dictionaries are based on Tcl’s hash tables, discussed previously in Chapter 
40, but Tcl’s C API provides a set of functions to deal with dictionaries as 
objects quite easily. 

You can use the 1c1_newpicton; function to create a new, empty dictionary. You 
can then add key-value mappings to the dictionary with the tc1_pictopjput 
function. For example, the previous section described a “tagged list” with a 
format such as max 105 min 89 average 96. Obviously, this is a dictionary format, 
and we could create it directly as a dictionary as follows: 
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Tcl_Obj *dictObj; 
Tcl Obj *objs[6]; 


int i; 

min = 89; 

max = 105; 
average = 96; 


objs{0] = Tcl 
objs{1] = Tcl 
objs(2] = Tcl 
objs[(3] = Tcl 
objs[4] = Tcl 


objs{5] = Tcl 
dictObj = Tcl 
for (i=0 ; i< 


_NewStringObj ("max", -1); 
_NewIntObj (max) ; 
_NewStringObj ("min", -1); 
_NewIntoObj (min) ; 
_NewStringObj ("average", -1); 
_NewIntObj (average) ; 
_NewDictoObj () ; 


6 ; i+=2) { 


Tel DictObjPut(interp, dictObj, objs[i], objs[{i+1]); 


} 


The rci_pictopjput function automatically increments the reference counts for 
both the key and the value if it proves necessary to store them in the 
dictionary (i.e., if they didn’t already exist in the dictionary). 


Note 


The dictionary object cannot be shared if you pass it to tc1_pictopjput OF 


any other funct 
is shared. 


ion that modifies a dictionary; a tc1_ Panic 1S triggered it if 


The rci_pictopjcet function retrieves a value associated with a key. For 


example, the follo 


wing code accesses the dictionary just created and 


retrieves a pointer to the object representing the value of the min key, storing 


it in the variable vai 


ue: 


Tcl_ Obj *key, *value; 


result int; 


key = Tcl NewStringObj("min", -1); 
result = Tcl_DictObjGet(interp, dictPtr, key, &value) ; 


The value stored in vaiue would be nuxz if the key didn’t exist. If the object 


referred to by aicte 


function returns tet. | 


er cannot be converted to a dictionary, the tc1_pictopjcet 


ERROR. 


If you map a key to a string value that has the form of a nested dictionary, 
that value is not automatically treated as a dictionary. For example, although 
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the value shown in the following code has the string format of a dictionary, 
it is still treated as a string: 


Tcl_Obj *key = Tcl_NewStringObj ("NAME", -1); 
Tcl Obj *value = Tcl_NewStringObj ( 
“{FIRST Dean LAST Akamine}", -1); 


Tel_Obj *dictObj = Tcl_NewDictoObj(); 
Tcl_DictObjPut(interp, dictObj, key, value); 


However, Tcl automatically converts the object to a dictionary 
representation if it is accessed with a dictionary function. On the other hand, 
if you know that you’re manipulating nested dictionary structures, you can 
use the tc1_pictopjputkeynist function, which accepts an array of key objects. 
For example, here is the implementation of Tcl’s aict set command function, 
which allows the user to specify any number of nested keys as arguments, 
followed by the value to map to the terminal key: 


static int 

DictSetCmd ( 
ClientData dummy, 
Tcl_Interp *interp, 
int objc, 
Tcl_ Obj *const *objv) 


Tcl Obj *dictPtr, *resultPtr; 
int result, allocatedDict = 0; 


if (objc < 4) { 
Tcl _ WrongNumArgs(interp, 1, objv, 
"varName key ?key ...? value"); 
return TCL ERROR; 


} 


dictPtr = Tcl ObjGetVar2(interp, objv[1], NULL, 0); 
if (dictPtr == NULL) { 

allocatedDict = 1; 

dictPtr = Tcl NewDictObj(); 
} else if (Tcl_IsShared(dictPtr)) { 

allocatedDict = 1; 

dictPtr = Tcl _DuplicateObj (dictPtr) ; 
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} 


result = Tcl_DictObjPutKeyList(interp, dictPtr, objc-3, 
objv+2, objv[objc-1]); 
if (result != TCL_OK) { 
if (allocatedDict) { 
TclDecrRefCount (dictPtr) ; 


} 


return TCL ERROR; 


} 


resultPtr = Tcl_ObjSetVar2(interp, objv[i], NULL, 
dictPtr, TCL _LEAVE_ERR MSG) ; 
if (resultPtr == NULL) { 
return TCL ERROR; 
} 


Tcl_SetObjResult(interp, resultPtr) ; 
return TCL OK; 


Note 


Notice how the function checks to see if the dictionary object is shared 
and, if so, duplicates it before modifying it. Otherwise, if the 
dictionary object were shared, the call to vc1_pictobjputkeyrist Would 
CauSe @ Tcl_Panic. 


The tci_pictopjsize function gives you the size of a dictionary (that is, the 
number of key-value mappings). You can remove a key-value pair from a 
dictionary using the rc1_pictopjremove function. This function also decrements 
the reference count of the objects representing the key and value in the 
dictionary. It is not an error if the key did not previously exist. For removing 
key-value pairs from nested dictionary structures, you can call the 
Tcl_DictObjRemovexeytist function, which accepts an array of keys, as with 
Tcl DictObjPutKeyList. 

Finally, you can iterate over the key-value pairs of a dictionary. The 
Tcl_DictobjFrirst function starts a traversal of a particular dictionary, returning 
the first key-value pair. Subsequent calls to tc1_pictopjnext 1terate through the 
key-value pairs. Each of these functions has a termination indicator to let 
you know if you’ve reached the end of the iteration. If you want to stop a 
search before you reach the end of the dictionary, you must call 
Tcl _DictobjDone to clean up the search state; you don’t need to call 


771 


Tcl_DictobjDone If tc1_pictobjnext reaches the end of the dictionary itself, though 
it’s not an error to do so. Each dictionary traversal has its own unique 
Tcl_Dictsearch token associated with it, which must be passed to each of these 
functions. 


Note 


If the value of the dictionary is modified during the iteration, either by 
tcl _Dictobj function calls or a function call that causes the object to 
change to a non-dictionary representation, the iteration is terminated. 
The next call to rc1 pictobjnext indicates that it has reached the end of 
the iteration. 


As an example of using the dictionary iterators, the following code creates a 
list consisting of all the values froma dictionary: 


Tcl_DictSearch search; 
Tcl Obj *key, *value, *valueList; 


int done; 
/* 
* Assume interp and objPtr are parameters. 
tf 
if (Tcl_DictObjFirst(interp, objPtr, &search, 
&key, &value, &done) != TCL_OK) { 


return TCL ERROR; 


} 
valueList = Tcl _NewListObj (0, NULL); 


for (; !done ; Tcl DictObjNext(&search, &key, &value, &done) ) { 
Tcl ListObjAppendElement (interp, valueList, value) ; 
} 


Tcl_DictObjDone (&search) ; 
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42. Channels 


Tcl provides an extremely flexible system for managing input and output 
based on the concept of channels. You are probably familiar with file and 
TCP socket channels at the Tcl level. They are two of the channel types that 
Tcl itself provides. The channel system was created in order to provide a 
flexible, extensible, cross-platform, device-independent means of dealing 
with input and output. The channel design takes a two-tiered approach: from 
Tel, or using a high-level approach in C, all channels are used in more or 
less the same way. Standard operations such as puts, reaa, chan flush, and so 
forth are the same for all channels, whatever lowlevel device (files, TCP 
sockets, real hardware devices, etc.) implements them. Lower-level drivers 
implement the specifics of each channel type, creating a bridge between the 
generic layer and the “device.” This design means that it 1s possible to 
create new channel types that behave exactly as built-in channels do. 

This chapter explains how to use channels from C and how to write a driver 
for a new channel type. 


42.1 Functions Presented in This Chapter 


Tcl provides a rich set of functions for interacting with channels. Most of 
these functions take a tc1_channe1 aS an argument or return it as a result. 


42.1.1 Basic Channel Operations 


The following functions perform basic channel operations such as opening, 
closing, reading, writing, and so on: 

® Tcl Channel Tcl FSOpenFileChannel (Tcl Interp interp, Tcl Obj 

*pathPtr, const char *modeString, int permissions) 

Opens a file specified by patnrer and returns a channel handle. The syntax 
and meaning of all arguments are similar to those given in the Tel open 
command when opening a file. (Replaces the older string-based 
Tcl_OpenFileChannel function. ) 

® Tcl Channel Tcl_GetStdChannel (int type) 
Returns a channel handle for a standard I/O channel, where type is one of 
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TCL STDIN, TCL STDOUT, OF TCL STDERR. 
® Tcl SetStdChannel (Tcl Channel channel, int type) 
Sets an existing channel to use as a standard I/O channel, where type is one 


Of tc. stpIN, TCL_stTDOUT, OF TCL STDERR. 


® int Tcl _Close(Tcl_Interp *interp, Tcl Channel channel) 


Destroys the channel. Buffered output is flushed to the channel’s output 
device prior to destroying the channel, and any buffered input is discarded. 
The channel should not be registered in any interpreter when tc1 close 1S 
called; call tei unregisterchanne1 instead. 
° int Tcl ReadChars (Tcl Channel channel, 
Tcl Obj *readObjPtr, int charsToRead, 
int appendFlag) 
Consumes bytes from channe1, converting them to UTF-8 based on the 
channel’s encoding and storing the produced data in reaaopjrtr’s string 
representation. The return value is the number of characters, up to 
charsToread, that were stored in reaaopjetr. If an error occurs while reading, 
the return value is -1. (Replaces the older tc1_reaa function, which doesn’t 
support encoding translation.) 
® int Tcl ReadRaw(Tcl Channel channel, char *readBuf, 
int bytesToRead) 
Similar to tci Readchars, except used by transformational channel drivers in 
stacked channel applications. bytesroreaa bytes are read from the channel 
below and copied to reacsur without encoding translation or other changes. 
* int Tcl _GetsObj (Tcl Channel channel, Tcl_Obj *lineObjPtr) 
int Tcl_Gets(Tcl_Channel channel, Tcl_DString *1lineRead) 
Tcl_Getsobj CONsSuMes bytes from channe1, converting them to UTF-8 based on 
the channel’s encoding, until a full line of input has been seen. All of the 
characters of the line except for the terminating end-of-line character(s) are 
appended to iineonjrrr’s string representation; the end-of-line character(s) 
are read and discarded. Returns the number of characters stored in 
lineobjPtr, OF -1 In case of an error condition or an end-of-file condition; also 
returns -1 and consumes no data on a non-blocking channel if a complete 
line of data was not available. 1c1 cets 18 the same as 1c1 Getsopj except the 
resulting characters are appended to the dynamic string given by tinereaa 
rather than a Tcl object. 
® int Tcl _Ungets(Tcl_ Channel channel, const char *input, 
int inputLen, int addAtEnd) 
Adds data from input to the input queue of a channel; inputzen gives the 
number of bytes to add. A nonzero value of aaaatena indicates that the data is 
to be added at the end of the queue; otherwise, it is to be added at the head 
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of the queue. tc1_ungets returMS inputzen, Or -1 1f an error occurs. 

® int Tcl WriteObj (Tcl Channel channel, 

Tcl Obj *writeObjPtr) 
int Tcl WriteChars(Tcl_ Channel channel, 
const char *charBuf, int bytesToWrite) 

Tcl Writeobj Writes the string representation of writeopjrtr to the channel, 
converting the characters to the channel’s encoding. tc1_writechars does the 
same, except charsur contains the UTF-8 characters; pytesrowrite specifies the 
number of bytes to write, or -1 to indicate that cnarsur is a nullterminated 
string and all characters should be written. (tc1_writecnars replaces the older 
tcl_write function, which doesn’t support encoding translation.) Returns the 
number of bytes written, or -1 in case of an error. 

® int Tcl WriteRaw(Tcl_ Channel channel, const char *byteBuf, 

int bytesToWrite) 

Similar to tc1 writechars, except used by transformational channel drivers in 
stacked channel applications. bytesrowrite bytes are read from pytesur and 
written to the channel below without encoding translation or other changes. 

® int Tcl _Eof(Tcl_Channel channel) 
Returns a nonzero value 1f cnanne1 encountered an end of file during the last 
input operation. 

® int Tcl_Flush(Tcl_Channel channel) 
Causes all of the buffered output data for channei to be written to its 
underlying file or device as soon as possible. 

® int Tcl _InputBlocked(Tcl_ Channel channel) 
Returns a nonzero value 1f channe1 18 in non-blocking mode and the last input 
operation returned less data than requested because insufficient data was 
available. The call always returns o if the channel is in blocking mode. 

® int Tcl _InputBuffered(Tcl_ Channel channel) 
Returns the number of bytes of input currently buffered in the internal buffers 
for a channel. If the channel is not open for reading, this function always 
returns o. 

* int Tcl OutputBuffered(Tcl_ Channel channel) 
Returns the number of bytes of output currently buffered in the internal 
buffers for a channel. If the channel is not open for writing, this function 
always returns o. 


sd Tcl WideInt Tcl Seek(Tcl_ Channel channel, 


Tcl WideInt offset, int seekMode) 
Moves the access point in channe1 where subsequent data is read or written. 
The requested access point is a signed byte orrset relative to the seexmoae, 
which is one of szex ser (Start), srex_cur (current position), or sx enn (end). 
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Buffered output is flushed to the channel, and buffered input is discarded, 
prior to the seek operation. Returns the new access point, or -1 in case of an 
error. 

® Tcl WideInt Tcl_Tell(Tcl_ Channel channel) 
Returns the current access point for a channel, or -1 1f the channel does not 
support seeking. 

® int Tcl _TruncateChannel (Tcl Channel channel, 

Tcl WideInt length) 

Truncates the file underlying channei to a given iength Of bytes. 
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int Tcl _GetChannelOption(Tcl_Interp *interp, 


Tcl Channel channel, const char *optionName, 


Tcl DString *optionValue) 
Retrieves the value of a channel option named optionvame and stores the result 
IN optionvaiue. If optionname 18 nuit, the function stores an alternating list of all 
channel option names and their values 1n optionvaiue. The interp can be nuit. 
* int Tcl SetChannelOption(Tcl_ Interp *interp, 

Tel Channel channel, const char *optionName, 

const char *newValue) 
Sets newvalue aS the value for the channel option given by optionname. The 
procedure normally returns rcz_ox. If an error occurs, it returns rct_eRRor} In 
addition, if interp is non-null, 1c1i_setchanneloption leaves an error message in 
the interpreter’s result. 


42.1.2 Channel Registration Functions 


The following functions manage the registration of channels with 
interpreters and threads: 
® void Tcl RegisterChannel (Tcl Interp *interp, 
Tcl Channel channel) 

Adds a channel to the set of channels accessible in interp. After this call, Tcl 
programs executing in that interpreter can refer to the channel in input or 
output operations using the name given in the call to tc1_createchanne1. The 
interp argument may be wuz to add a reference to the channel independent of 
any interpreter. 


int Tcl _UnregisterChannel (Tcl Interp *interp, 


Tcl Channel channel) 


int Tcl DetachChannel (Tcl Interp *interp, 


Tcl Channel channel) 


Removes a channel from the set of channels accessible in interp. After this 
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call, Tcl programs can no longer use the channel’s name to refer to the 
channel in that interpreter. The interp argument may be nutz to remove a 
reference to the channel independent of any interpreter. In the case of 
Tcl _UnregisterChannel, 1f this operation removes the last registration of the 
channel in any interpreter, the channel 1s also closed and destroyed. 

® int Tcl_IsChannelShared(Tcl_Channel channel) 


Returns 1 if channe1 is Shared among multiple interpreters, otherwise o. 


int Tcl_IsChannelRegistered(Tcl_ Interp *interp, 


Tcl Channel channel) 


void Tcl CutChannel (Tcl Channel channel) 
Removes the specified channel from the list of all channels belonging to the 
current thread (if threads are present). The operation may not be performed 
on channels registered with an interpreter. 


® void Tcl SpliceChannel (Tcl Channel channel) 


Adds the specified channel to the list of all channels belonging to the current 
thread (if threads are present). The operation may not be performed on 
channels registered with an interpreter. The channel must have been 
previously cut from a thread with tc1_cutthreaa. 


42.1.3 Channel Attribute Functions 


The following functions allow you to query or set attributes of a particular 
channel: 


int Tcl IsChannelExisting (CONST char *channelName) 
Returns i if a channel with the given name exists, o otherwise. 
® int Tcl_IsStandardChannel (Tcl_Channel channel) 
Returns : if the channel is one of the three standard channels—stain, stdout, 
OF stder-—o Otherwise. 


® ClientData Tcl _ GetChanneliInstanceData(Tcl Channel channel) 


Fetches the instance data for a given channel. 


ad Tcl ChannelType *Tcl_GetChannelType (Tcl Channel channel) 
Fetches a pointer to the channel’s type. 
® CONST char *Tcl_ GetChannelName (Tcl Channel channel) 


Returns the name of a given channel. 


int Tcl _GetChannelHandle(Tcl_ Channel channel, 

int direction, ClientData handlePtr) 
Places the OS-specific device handle (such as a rizz «) associated with a 
channel and direction (tcL_READABLE or TCL_WRITABLE) IN handiertr. Returns 
tc. ERRor If there 1s no handle. 
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bf Tcl ThreadId Tcl _GetChannelThread(Tcl_ Channel channel) 
Returns the ID of the thread currently managing the given channel. 
int Tcl _GetChannelMode (Tcl Channel channel) 
Returns an ORed combination of tct reapasie and rc. wertaBie. 
® int Tcl_GetChannelBufferSize(Tcl_ Channel channel) 
Returns the channel’s buffer size, in bytes. 
® Tcl _SetChannelBufferSize(Tcl_Channel channel, int size) 
Sets the channel’s buffer size, in bytes. 


int Tcl_IsChannelRegistered(Tcl_Interp interp, 


Tcl Channel channel) 


Returns 1 if channe1 has been registered in interpreter interp, otherwise o. 


42.1.4 Channel Query Functions 


The following functions provide tools for retrieving information about 
channels in an interpreter: 
* Tcl Channel Tcl GetChannel(Tcl_Interp interp, 
const char *channelName, int *modePtr) 
Given the name of a channel handle in Tcl, returns the tc1_ cnanne1 associated 
with it and the moaerer, which is an integer ORed combination of tct_Reapaste 


and tct wRITaBLe. 


® int Tcl GetChannelNames (Tcl _Interp interp) 


int Tcl_GetChannelNamesEx(Tcl_Interp interp, 
const char *pattern) 
Writes the names of the registered channels to the interpreter’s result as a 
list object. tci_cetchanneiNamesex filters these names according to the pattern 
using the same syntax as string match. 


42.1.5 Channel Type Definition Functions 


The following functions are related to creating and using custom channel 
types: 
® Tcl Channel Tcl_CreateChannel ( 
Tcl ChannelType *typePtr, CONST char *channelName, 
ClientData instanceData, int mask) 
Creates a new channel of type typerer with name channeiname. 
® Tcl Channel Tcl StackChannel (Tcl_Interp interp, 


Tcl ChannelType *typePtr, ClientData instanceData, 
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int mask, Tcl Channel channel) 

Stacks a new channel on an existing channei1 with the same name that was 
registered for channei by 1c1_Registerchannel. The mask parameter specifies the 
operations that are allowed on the new channel. These can be a subset of the 
operations allowed on the original channel. Other options are as for 
Tcl_CreateChannel. 

® int Tcl _UnstackChannel (Tcl Interp interp, 

Tcl Channel channel) 

Reverses the process of stacking a channel. The old channel is associated 
with the channel name, and the processing module added by tc1_stackchanne1 
is destroyed. If there is no old channel, tci_unstackchannei 18 equivalent to 
Tcl Close. 

® Tcl Channel Tcl_GetStackedChannel (Tcl_Channel channel) 


Returns the channel in the stack of channels that is just below the supplied 


channel. 


® Tcl Channel Tcl _GetTopChannel (Tcl Channel channel) 
Returns the top channel in the stack of channels of which the supplied cnanne1 
is a part. 

® int Tcl BadChannelOption(Tcl_ Interp *interp, 

CONST char *optionName, CONST char *optionList) 

Called from the channel option get/set functions to indicate that optionname 1S 
not a valid option for this channel. 

® Tcl NotifyChannel (Tcl Channel channel, int mask) 
Called by the channel driver to indicate to the generic layer that the events 
specified by masx (an OR’ed combination of tci reapasie, tc werraste, and 
tcL_exception) have occurred. 


void Tcl _ClearChannelHandlers (Tcl Channel channel) 
Removes all channel handlers and event scripts associated with the 
specified channel. 
* int Tcl ChannelBuffered(Tcl_ Channel channel) 
Returns the number, in bytes, currently in the channel’s input buffer. 


42.2 Channel Operations 


Tcl provides a rich set of operations, described in Section 42.1.1, for 
interacting with channels. Most of these functions take a tc1_cnanne1 Structure 
as an argument or return it as a result. The following code shows the 
definition of a command function implementing a fi1etovar command: 
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static int 
FileToVarCmd(ClientData clientData, Tcl_Interp *interp, 


} 


int objc, Tcl_Obj *CONST objv[]) { 
Tcl_Channel chan; 
Tcl Obj *buffer; 


if (objc != 3) { 
Tcl_WrongNumArgs(interp, 1, objv, "file varname") ; 
return TCL ERROR; 


} 


chan = Tcl FSOpenFileChannel(interp, objv[1], "r", 0); 
if (chan == NULL) { 

return TCL ERROR; 
} 


buffer = Tcl_NewObj () ; 

if (Tcl_ReadChars(chan, buffer, -1, 0) < 0) { 
Tcl_Close(interp, chan); 
return TCL_ERROR; 


} 


Tcl_Close(interp, chan) ; 


Tcl SetVar2Ex(interp, Tcl_GetString(objv[2]), 
NULL, buffer, 0); 


return TCL OK; 


The idea is that executing the following from a script 


filetovar /tmp/somefile content 


has the same effect as 


set fid [open /tmp/somefile ] 
set content [read $fid] 
close $fid 


The command procedure expects two arguments the name of a file to read 
and the name of a variable in which to store the content. The 
Tcl_FSOpenFileChanne1 function takes a Tcl object containing the file name to 
open and a mode string that is interpreted in the same way as the mode 
argument to Tcl’s open command. It returns a tci_channe1 object that can then 
be passed to other channel I/O commands. 
The actual read is taken care of by the vc1_Reaachars command, which takes as 
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arguments a channel, a Tcl object in which to place the data, the length of 
data to read, and a flag indicating whether the data should be appended or 
not. In this case, the length argument is -1, which tells 1c1_Reaachars to read the 
entire file. This function is similar to the Tcl reaa command. tc1 close then 
closes the file, and the content is assigned as the value of the variable using 
Tcl_SetVar2Ex. 

As you can see, most of the channel functions used in this example are 
analogous to Tcl script-level commands. Likewise, most of the Tcl I/O 
commands have roughly equivalent C functions, as shown in Table 42.1. 
Especially useful are the ci cetchanneloption and tcl _setChanneloption 
commands, which let us get and set channel options. The following sets the 
buffer size for a channel: 


Tcel_SetChannelOption(interp, chan, "-buffersize", 10000"); 


Table 42.1 Tcl Channel Commands and Analogous C Functions 


Tcl command Analogous C functions 

open Tcl_FSOpenFileChannel for files 

exec, "open [* Tel_OpenCommandChannel (discussed in further detail in 

Chapter 45) 

close Tcl Close 
“puts ; Tcl WriteObj,Tcl WriteChars,Tcl WriteRaw 
read Tcl ReadChars, Tcl ReadRaw 

gets Tcl_Gets,Tcl_GetsObj 

chan eof Tcl Eof 

chan blocked Tcl _ InputBlocked 

chan flush Tcl Flush 

“chan seek | Tcl_Seek 

chan tell Tcl Tell 

chan truncate Tcl_TruncateChannel 

chan configure Tcl_GetChannelOption, Tcl_SetChannelOption 
“chan pending ; Tcl _InputBuffered, Tcl OutputBuffered 


The next example retrieves the address, host name, and port number on a 
socket channel and stores the results into a pstring: 


Tcl DString optionValue; 


Tel DStringInit (optionValue) ; 
Tcl_GetChannelOption(interp, chan, "-sockname", &optionValue) ; 
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There are also several functions for querying attributes of the channel, as 
listed in Section 42.1.3. 


42.3 Registering Channels 


If you create a channel in Tcl (e.g., with open), a channel identifier is 
returned that lets you manipulate the channel from the scripting level. On the 
other hand, if you create a channel using Tcl’s C API, the channel is not 
automatically exposed at the scripting level. You would have to do all 
channel interaction at the C level with tc1 cnanne1. 

If you want to expose a channel to the scripting level, you must call the 
Tcl_RegisterChannel function to register it in each interpreter in which you want 
to access it. You can register a channel in as many interpreters as you like, 
as long as they are in the same thread. 

The following code implements a randomfile package. It opens the Unix 
/dev/random file as a source of random data, sets the channel encoding to 
binary, and registers the channel with the Tcl interpreter. Then it retrieves 
the name of the channel created and assigns it to the variable random: 
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#include <tcl.h> 


int Randomfile Init (Tcl_Interp *interp) { 
Tcl_ Channel chan; 
Tcl_ Obj *filename; 
#ifdef USE_TCL_STUBS 
if (Tcl_InitStubs(interp, "8", 0) == NULL) { 
return TCL_ERROR; 
} 


#endif 


filename = Tcl NewStringObj ("/dev/random", -1); 
Tcl_IncrRefCount (filename) ; 

chan = Tcl_FSOpenFileChannel(interp, filename, "r", 0); 
Tcl_DecrRefCount (filename) ; 


if (chan == NULL) { 
return TCL ERROR; 
} 


Tcl _SetChannelOption(interp, chan, "-encoding", 
"binary") ; 
Tcl RegisterChannel(interp, chan); 
Tcl_SetVar(interp, "random", 
Tcl GetChannelName(chan), 0); 


if ( Tcl _ PkgProvide(interp, 
"“randomfile", 
"0.1") t= TCL_OK ) { 
return TCL_ERROR; 


} 


return TCL OK; 


} 


Once you have compiled this code and loaded it into a Tel script, you could 
read 10 bytes of random data with a command like 


read $random 10 


Once you have registered a channel with Tcl, you should not close it from 
the C level with tci_ciose. The proper way to remove a channel from the Tcl 
interpreter is with the rc1_unregisterchanne1 function, which makes the channel 
invisible to the specified interpreter and, if there are no more references to 
it, closes it. In contrast, tcl petachchanne1 removes the channel from an 
interpreter but does not attempt to close it. 

Although you can share a channel with multiple interpreters, all of those 
interpreters must be in the same thread. You cannot share channels across 
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threads. However, you can move a channel from one thread to another. To 
do so, the channel must not be registered with any interpreters; call 
Tcl _DetachChannel 1f necessary. Then you must “cut” the channel from its 
current thread with the rc1_cutchanne1 function. After the channel is no longer 
associated with a particular thread, you can then call tci_ spiicechannei from a 
thread to associate the channel with that thread. See Chapter 46 for more 
information about threaded Tcl programming. 

You can also get a tc1_channe1 handle for a channel even if it was created at 
the scripting level. Given the name of a channel, such as fiiei, the 
Tcl_GetChannel function returns a tci_channei for It: 


Tcl_ Channel chan; 
int mode = 0; 
chan = Tcl _GetChannel(interp, "file 1", & mode); 


42.4 Standard Channels 


You are probably already familiar with using Tcl’s standard channels: stain, 
stdout, aNd stderr (covered in Chapter 11). It is possible to manipulate them 
from C, which is useful if you want to replace one of the standard channels 
with one of your own creation. 

The tci cetstachanne1 function returns a channel handle for a standard I/O 
channel. The only argument is one of tci story, rct_stpour, OF TcL_sTpERR. YOU 
can also use an existing channel as a standard I/O channel with the 
Tcl_SetStdChannel function: 


Tcl SetStdChannel(myChan, TCL_ STDOUT); 
Tcl_RegisterChannel(NULL, myChan); 


Note 


The call to tci_Registerchannel after rc1_setstdchannel 18 required in current 
versions of Tcl. See the reference documentation for more information. 


As an example of how this feature is used, Apache Rivet creates a special 
Apache channel that uses the Apache web server’s API to send data through 
the server to the browser. Rivet sets this channel as the standard output 
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channel, so that regular puts commands, such as puts "Hello, worla", are 
redirected to the Apache channel instead of the normal standard output. This 
means that ordinary Tcl scripts can be run inside Apache without 
modification. 


Note 


If one of the standard channels is set to nott, either by calling 
Tol _SetStdachanne1 With a nurz channel argument or by calling 1c1_ ciose on 
the channel, then the next call to tci_ createchanne1 automatically sets the 
standard channel with the newly created channel. If more than one 
standard channel is nutt, the standard channels are assigned starting 
with standard input, followed by standard output, and standard error 
last. 


42.5 Creating a New Channel Type 


As stated earlier, Tcl provides a complete API for the creation of new 
channel types. Examples of extensions that implement new channel types are 
UDP sockets; the memchan memory channel implementation, which lets you 
read and write to memory as if it were a file; and Rivet’s Apache channel, 
which uses the Apache web server’s C API to send data to the browser. 

The central concept in creating a new driver type is to implement the 
functions that carry out the different tasks a driver performs, such as 
reading, writing, flushing, and so on. The basic structure that represents a 
channel type 18 tc1_channel Type! 
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typedef struct Tcl ChannelType { 
char *typeName; 
Tcl _ChannelTypeVersion version; 
Tcl DriverCloseProc *closeProc; 
Tcl _ DriverInputProc *inputProc; 
Tcl_DriverOutputProc *outputProc; 
Tcl_DriverSeekProc *seekProc; 
Tcl _DriverSetOptionProc *setOptionProc; 
Tcl DriverGetOptionProc *getOptionProc; 
Tcl _DriverWatchProc *watchProc; 
Tcl_DriverGetHandleProc *getHandleProc; 
Tcl_DriverClose2Proc *close2Proc; 
Tcl _DriverBlockModeProc *blockModeProc; 
Tcl_ DriverFlushProc *flushProc; 
Tcl _DriverHandlerProc *handlerProc; 
Tcl_DriverWideSeekProc *wideSeekProc; 

} Tcl_ChannelType; 


Each entry is a pointer to a function that carries out a particular operation. 
You don’t need to provide a function for each channel operation; you can set 
several of the fields to wun. if they don’t apply, or implement a function that 
returns ernva, when called to indicate that the operation is not meaningful on 
the channel. See the reference documentation for a complete description of 
the function signatures, their purposes, and which ones are required. We’ll 
see an example of a custom channel type later in Section 42.5.3. 


42.5.1 Creating a Custom Channel Instance 


After you have implemented your channel type and defined its channel 
operation functions, you can create instances of the channel type with the 
Tcl_CreateChannel function: 


Tcl_Channel Tcl_CreateChannel ( 
Tcl_ChannelType *typePtr, CONST char *channelName, 
ClientData instanceData, int mask) 


The typertr 18 a pointer to a previously defined rc1_channeitype structure. The 
name used by channeiname must be unique (such as fiie1, file2, sock7, socks, and 
so on). The instancepata variable is your chance to pass some instance- 
specific data to the channel implementation. Last, the masx instructs Tcl what 
operations to allow on the channel, using the following flags: 

* tcL_wrttasLe—Writing 1s allowed. 
® TCL _READAB =—Reading is allowed. 
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Once you register a channel type with Tcl by creating a channel of that type, 
the channel type cannot be removed. 


42.5.2 Stacked Channels 


In Tel, not only is it possible to create new drivers for specific “devices,” it 
is also possible to create stacked channels, which do not directly talk with a 
device but act as intermediary filter layers between Tcl and some other 
channel. rcirzs, the Tcl interface to OpenSSL, works this way. It doesn’t 
actually create the socket that talks with the web server but adds an SSL 
filter between the socket and Tcl. 

To add a channel to a stack, use tc1_stackchannel! 


Tcl_Channel Tcl_StackChannel (Tcl_Interp interp, 
Tcl ChannelType *typePtr, ClientData instanceData, 
int mask, Tcl_Channel channel) 


Aside from the ever-present interpreter, the function takes a pointer to a 
Tcl _Channeltype Structure, such as that illustrated in the preceding example, 
instance data, a mask describing the mode (ct reapasiz, cL wetTaBLE, OF 
tcL_exception), and the channel to layer on top of. The newly created top 
channel structure is returned. 

Once the channel is stacked, if any function tries to perform I/O on the 
original channel, such as with tc1 Readchars OF Tcl writechars, the system 
automatically redirects such calls to the channel on top of the stack. In other 
words, all tci_channei tokens stay valid, independently of where they are ina 
stack, but there is no “back door” access through these standard I/O 
functions. At the scripting level, Tcl automatically reassigns the symbolic 
channel identifier to refer to the top channel in the stack. 

It is possible to unstack a channel with 1ci_unstackchannei. This 1s useful in the 
case where you wish to remove a filter—perhaps you no longer want to 
encrypt output to a file. It has a simple prototype: 


int Tcl UnstackChannel(Tcl_Interp interp, 
Tcl_Channel channel) 


The old channel is associated with the symbolic channel name, and the 
processing module added by tc1_stackchanne1 18 destroyed. If channei refers to 
an unstacked channel, 1ci_unstackchanne1 18 equivalent to rc1_ close. 


42.5.3 ROT13 Channel 


788 


As an example of creating custom channel types, this section describes a 
stacked channel type that implements the “ROT13” cipher. This is an ancient 
method of encrypting messages. It works by taking a character, “rotating” 13 
places down the alphabet, and using that letter in its place. For instance, the 
letter 2 becomes n, » becomes o, and so on. Using 13 as the number to shift 
each letter also has the advantage that performing a second ROT13 
transformation “deciphers” the text. Of course, ROT13 is not in any way, 
shape, or form secure in this day and age, but it makes for a simple example 
that gives you an idea of what can be done with channels. 

Since we are working with a filter, rather than an “endpoint” driver that 
talks with some device or library external to Tcl, we need a means of 
attaching our channel to a Tcl channel that is already open. To accomplish 
this, we create a command, aaarot, which takes a channel as an argument and, 
optionally, a number to use in place of 13. Ina Tcl script, it looks like this: 


set fl [open /tmp/outfile w] 
addrot $fl 


Here is the command function to implement the aaarot command: 


/* This structure serves as the instance data that gets 
* passed to the channel driver functions. */ 


typedef struct { 
Tcl_Channel self; 
Tcl Channel parent; 
int rotate; 

} RotInstance; 


static int 
AddRotCmd(ClientData clientData, Tcl_Interp *interp, 
int objc, Tcl_Obj *CONST objv[]) { 
Tcl_ Channel parent; 
int modePtr = 0; 
int rotate = 0; 
RotInstance *rotinstance; 


if (objc < 2) { 
Tcl_WrongNumArgs(interp, 1, objv, "chan ?rotation?") ; 
return TCL ERROR; 

} 

/* Get the channel from its name, fail if it's 

* not a valid channel. */ 
parent = Tcl GetChannel(interp, Tcl_GetString(objv[1]), 
&modePtr) ; 
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if (parent == NULL) { 
Tcl AppendResult (interp, Tcl _GetString(objv[i]), 
"is not a valid channel", NULL); 
return TCL ERROR; 


} 


/* We take an additional argument that is the amount 
* to 'rotate' for our cipher. */ 


if (objec == 3) { 
if (Tcl_GetIntFromObj ( 
interp, objv[2], &rotate) != TCL_OK) { 


return TCL ERROR; 


rotinstance = 
(RotInstance *)Tcl_Alloc (sizeof (RotInstance) ) ; 


rotinstance->rotate = rotate; 
rotinstance->parent = parent; 


/* Stack the channel. */ 

rotinstance->self = Tcl_StackChannel ( 
interp, &RotChan, (ClientData) rotinstance, 
modePtr, parent); 


return TCL OK; 


} 


The call to tc1 cetchanne1 returmS @ tcl channe1 Structure for the channel 
identifier of the existing channel. This channel is the “real” channel that 
actually sends or pulls data from a file, the channel that our stacked channel 
reads from or writes to. The code then fills in the fields of a rotinstance 
structure that stores the number of characters to rotate for this instance of the 
channel and the handle to the original channel. Finally, we use 
Tcl_StackChannel to Stack the channel, passing the xotinstance structure as 
instance data. This is where the new channel is created and layered on top 
of the existing channel. If we were creating a driver for a special device, 
we would call tc1_ createchannei 1n this command instead of tc1_stackchannel. 
The key to understanding the new channel’s capabilities is in the rotchan 
structure, which is declared in this way: 
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static 
Tcl_ChannelType RotChan = { 


bs 


"rot13_ channel", 
TCL_CHANNEL_VERSION_3, 
RotcloseProc, 
RotinputProc, 
RotoutputProc, 
NULL, 
RotsetOptionProc, 
RotgetOptionProc, 
RotwatchProc, 
RotgetHandleProc, 
NULL, 

NULL, 

NULL, 

NULL, 

NULL 


Our channel filter is not particularly complex. rotcicserroc does nothing more 
than call ci Free to free the storage allocated for the instance data. 
RotwatchProc does nothing, and rotgetHandieProc returns an error, because there 
is no lowlevel handle to return. 

We’ll examine the output and input functions in detail. In order to define 
what we’re doing clearly, output is when Tcl is sending data out, such as 
with the puts command, and input is when data is being read, such as with 


read OF gets. 


static int 
RotoutputProc (ClientData instanceData, CONST84 char *buf, 


} 


int toWrite, int *errorCodePtr) { 
RotInstance *rotinstance = (RotInstance *)instanceData; 
char *outbuf; 


outbuf = Tcl _ Alloc(toWrite) ; 
roti3 (buf, outbuf, toWrite, rotinstance->rotate); 


/* We have pushed the data down to the next layer 
* of the stack. */ 


Tcl_WriteRaw(rotinstance->parent, outbuf, toWrite); 
Tcl_Free (outbuf) ; 
return towrite; 


Output functions take four arguments: instance data, a buffer containing data 
to output, how many bytes the buffer holds, and a pointer to an integer that 
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can hold a POSIX error code should a problem occur. 

RotoutputProc allocates a second buffer to contain the transformed text and 
performs the roti3 operation, which fills the outbus buffer with the encoded 
data. The tricky part is the call to tc1 writeraw. You must use this write 
function with stacked channels instead of a function like tc1 writechars. We do 
this because we are acting as a filter and must therefore write to the next 
channel down the stack, which we saved in the instance data when it was 
created. On the other hand, Tcl automatically redirects calls to functions like 
Tcl_Writechars to the top channel ina stacked channel. 

Were this not a stacked channel (1.e., not a filter), instead of writing to 
another layer of Tcl, we would write to a specific device. For instance, 
Apache Rivet’s output channel sends the data from the web server to the 
browser by calling the Apache API—ap rwrite (but, towrite, globals->r)— 
which hands off the buffer to Apache. In the preceding code, after freeing 
the memory associated with the output buffer, we also return how much data 
was actually written. In our case, this always equals the amount of data we 
were asked to write, so we can simply return that value. Especially in the 
case of non-blocking channels, these numbers are a bit trickier; see the 
reference documentation for details. 

The input function is activated when we read froma channel; for instance: 


set fl [open /tmp/outfile ] 
addrot $fl 
set data [read $fl] 


During the read, the Tcl library calls this function to receive data from our 
channel: 
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static int 
RotinputProc(ClientData instanceData, char *buf, 
int bufSize, int *errorCodePtr) { 
RotInstance *rotinstance = (RotInstance *)instanceData; 
char *inbuf; 
int read = 0; 


inbuf = Tcl Alloc(bufSize) ; 


/* We need to read the data from the next 
* layer of the stack. */ 


read = Tcl ReadRaw(rotinstance->parent, inbuf, bufSize); 
roti3(inbuf, buf, read, rotinstance->rotate) ; 

Tcl _ Free (inbuf) ; 

return read; 


} 


Input functions have four variables passed to them: instance data; a buffer to 
write data to (remember that Tcl wants to read data from this function); the 
amount of data the buffer can hold; and, again, a pointer to an int where we 
can store an error code. For our channel, the functionality of the input 
implementation is the reverse of the output function. Because it is a simple 
filter, we don’t have the data ourselves and have to fetch it from the next 
channel over, via tc1_Reacraw, noting how many characters were actually 
read. Analogous to the case of writing, we must use this read function with 
stacked channels instead of a function like ci Reaachars, Which Tel 
automatically redirects to the top channel in a stacked channel. We then 
“decipher” the data with the rotis function into the input buffer bus, free the 
allocated input buffer, and let Tcl know how many bytes are waiting to be 
collected in pus by returning the number we read from the next channel over. 
Since we’re only performing filtering operations, we don’t have to do 
anything with the file itself. 

Given that channels are an I/O system, the input and output functions are 
really the heart of what must be written. Tcl, via chan configure, also provides 
a means to configure options on channels. We can use this to give users a 
way to change the “rotate” number via a tc1_priversetoptionProc function. The 
Tcl code 


puts [fconfigure $fl -rotate 10] 


eventually causes the following function to be called. As arguments, it takes 
an instance data pointer, an interpreter, the name of the option to set (- 
rotate), and the string value of the option (10). 
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static int 
RotsetOptionProc(ClientData instanceData, Tcl_Interp *interp, 
CONST char *optionName, CONST char *newValue) { 


RotInstance *rotinstance = (RotInstance *)instanceData; 
if (stremp(optionName, "-rotate") == 0) { 
if (Tcl_GetInt(interp, newValue, 
& (rotinstance->rotate)) != TCL_OK) { 


return TCL ERROR; 


} 


return TCL OK; 


} 


return Tcl BadChannelOption(interp, optionName, 
"rotate"); 


} 


As there is only one possible option name, we check for it and attempt to set 
the value accordingly. If we are given a bad option name, 1c1_Badchanneloption 
is used to return an error with the incorrect name in the optionname parameter 
and a list of the possible names, without the leading hyphen. 

There is also a corresponding function to fetch information about current 
options. It can either return information about one option in particular, such 
aS -rotate, Or it can return information about all options. From Tel the two 
cases look like this: 


set rotate [chan configure $fl -rotate] 
set alloptions [chan configure $fl] 


The function to get options takes the same arguments as the option set 
function, with the exception of a 1c1_pstring where the result is appended. A 
nutt Value for optionName 18 a request for all possible options and their values. 
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static int 
RotgetOptionProc(ClientData instanceData, Tcl_Interp *interp, 


} 


CONST char *optionName, Tcl DString *optionValue) { 
RotInstance *rotinstance = (RotInstance *)instanceData; 
Tcl_Obj *rotval; 


if (optionName != NULL && 
strcemp(optionName, "-rotate") != 0) { 
return Tcl BadChannelOption({interp, optionName, 


“rotate"™) ; 
} 
rotval = Tcl_NewIntObj (rotinstance->rotate) ; 
if (optionName == NULL) { 
Tcl DStringAppendElement (optionValue, "-rotate") ; 
} 


Tcl DStringAppendElement (optionValue, 
Tel_GetString(rotval)); 
return TCL OK; 


When dealing with a stacked channel, we have to consider that not only is 
our rotate option visible, but also all the options of the underlying channel 
or channels, in this case the file channel. In the preceding code, we first 
check to make sure that the request is valid and returns an error via 
Tcl_BadChanneloption If it is not. We then append the results to the vstring—just 
the rotate value if -rotate was specified to chan configure, otherwise both the 
string -rotate and the value. 

Finally, we have a simple implementation of the ROT13 algorithm itself: 
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static void 

roti3(char *in, char *out, int len, int rot) { 
int i; 
int inc; 
int outc; 


for (i = 0; i < len; i ++) { 
ine = in[i]; 
if (inc >= 65 && inc <= 90) { /* A-Z */ 
if (ine + rot > 90) { 
outc = 64 + ((inc + rot) - 90); 
} else { 
oute = inc + rot; 
} 


} else if (inc >= 97 && inc <= 122) { /* a-z */ 
if (inc + rot > 122) { 
oute = 96 + ((inc + rot) - 122); 
} else { 
outc = inc + rot; 


} else { /* Other characters passed through. */ 
outc = inc; 
} 


out[i] = outc; 
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43. Handling Events 


This chapter describes Tcl’s library functions for event handling. The code 
you will write for event handling is divided into three parts. The first part 
consists of code that creates event handlers: it informs Tcl that certain 
callback functions should be invoked when particular events occur. The 
second part consists of the callbacks themselves. The third part consists of 
top-level code that invokes the Tcl event dispatcher to process events. 

Tcl supports two principal kinds of events: file events and timer events. Tcl 
also allows you to create idle callbacks, which cause functions to be 
invoked when Tcl runs out of other things to do; idle callbacks are used in 
Tk to defer redisplays and other time-consuming computations until all 
pending events have been processed. 


43.1 Functions Presented in This Chapter 


Tcl’s functions for event handling are the following: 


® void Tcl CreateChannelHandler (Tcl Channel channel, 


int mask, Tcl _FileProc *callback, 

ClientData clientData) 
Arranges for caiipack to be invoked whenever one of the conditions indicated 
by masx occurs for the channel whose handle is channei. 


® void Tcl DeleteChannelHandler (Tcl Channel channel, 


Tcl FileProc *callback, ClientData clientData) 
Deletes the handler for cnanne: that matches a previous invocation of 
Tcl_CreateChannelHandler With the given caiiback and clientpata arguments. 


©. Tcl TimerToken Tcl CreateTimerHandler (int milliseconds, 


Tcl TimerProc *callback, ClientData clientData) 
Arranges for callback to be invoked after miitiseconas have elapsed. Returns a 
token that can be used to cancel the callback. 


® void Tcl DeleteTimerHandler (Tcl _TimerToken token) 


Cancels the timer callback indicated by toxen, if it has not yet triggered. 


void Tcl_DoWhenIdle(Tcl_ IdleProc *callback, 
ClientData clientData) 
Arranges for caiipack to be invoked when Tcl has nothing else to do. 


® void Tcl CancelIdleCall(Tcl_IdleProc *callback, 
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ClientData clientData) 


Deletes any existing idle callbacks for ca1ipack and clientpata. 


void Tcl _DoOneEvent (int flags) 
Processes a single event of any sort and then returns. riags is normally o but 
may be used to restrict the events that are processed or to return 
immediately if there are no pending events. 

* void Tcl SetMainLoop(Tcl_ MainLoopProc *mainLoopProc) 
Installs a main-loop function into Tcl that will be called by tci_main after the 
processing of the application startup code (including the script specified on 
the command line). 

® void Tk MainLoop (void) 
Convenience function that processes events until every window created by 


this thread has been destroyed. Available only when Tk is present. 


43.2 Channel Events 


Event-driven programs like network servers or Tk applications should not 
block for long periods of time while executing any one operation, because 
this prevents other events from being serviced. For example, if a Tk 
application attempts to read from its standard input at a time when no input 
is available, the application blocks until input appears. During this time the 
process is suspended by the operating system so it cannot service GUI 
events. This means, for example, that the application cannot respond to 
mouse actions or redraw itself. Such behavior is likely to be annoying to 
users, since they expect to be able to interact with the application at any 
time. 

Channel handlers provide an event-driven mechanism for reading and 
writing channels that have long I/O delays. The function 
Tcl_CreateChannelHandler Creates a new file handler: 


void Tcl_CreateChannelHandler(Tcl_ Channel channel, 
int mask, Tcl_FileProc *callback, 
ClientData clientData) 


The channei argument gives the handle for an existing Tcl channel and may 
refer to many different types of channel (e.g., network sockets, serial lines, 
pipes, etc.), and masx indicates when caiipack should be invoked. It is an 
ORed combination of the following bits: 

Tcl should invoke caiinack Whenever data is waiting to 


® TCL READABLE 
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be read on channel. 
* vcr wrttaBLe——Icl should invoke caiipack Whenever channei 18 capable of 
accepting more output data. 
* rct_exceptron—Icl should invoke caiipack whenever an exceptional 
condition is present for channel. 
The channe1 argument must match the following prototype: 


typedef void Tcl FileProc(ClientData clientData, int mask); 


The ciientpata argument is the same as the ciientpata argument to 
Tel_CreateChannelHandler, aNd mask contains a combination of the bits rct Rzapaste, 
TCL WRITABLE, ANd tci exception to indicate the state of the channel at the time of 
the callback. You can place as many different callbacks on a channel at once 
as you wish as long as they all have distinct caiiback and clientpata values. 

To delete a file handler, call tei pe1etechanneixandier With the same channel, 
callback, aNd ciientpata arguments that were used to create the handler: 


void Tcl DeleteChannelHandler(Tcl_ Channel channel, 
Tel FileProc *callback, ClientData clientData) 


Note 


You can temporarily disable a particular channel callback by calling 
Tcl. CreateChannelHandler With a mask of o. You then can call 
Tcl_CreateChannelHandler again to reset the mask when you want to re- 
enable the handler. This approach is more efficient than calling 
Tcl _DeleteChannelHandler to delete the handler. 


With channel handlers you can do event-driven file I/O. Instead of opening a 
channel, reading it from start to finish, and then closing the channel, you 
open the channel, create a channel handler for it, and then return. When the 
channel is readable, the callback is invoked. It issues exactly one read 
request for the channel, processes the data returned by the read, and then 
returns. When the channel becomes readable again (perhaps immediately), 
the callback is invoked again. Eventually, when all of the data from the 
channel has been read, the channel becomes readable and the read call 
returns an end-of-file condition. At this point the channel can be closed and 
the channel handler deleted. With this approach, your application is still 
able to respond to other incoming events even if there are long delays in 
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reading the channel. 
For example, wisn uses a file handler to read commands from its standard 
input when it is connected to a real console. The main program for wisn 
creates a channel handler for standard input (file descriptor 0) with the 
following statement: 


Tcl Channel inChan = Tcl GetStdChannel (TCL STDIN) ; 

Tcl_CreateChannelHandler(inChan, TCL READABLE, 
StdinProc, (ClientData) inChan) ; 

Tcl_DStringInit (&command) ; 

Tcl DStringInit (&line) ; 


In addition to registering stainproc as the callback for standard input, this 
code initializes a dynamic string that is used to buffer lines of input until a 
complete Tcl command is ready for evaluation, and another dynamic string 
that is used to read lines of text from the channel. The main program enters 
the event loop as described in Section 43.5. When data becomes available 


on standard input, stainrroc is invoked. Its code! is as follows: 


1. The real implementation of stainproc is considerably more complex 
because of the use of thread-specific data to enable multithreaded operation 
of Tk. 


void StdinProc(ClientData clientData, int mask) { 
Tcl_ Channel chan = (Tcl Channel) clientData; 
Tcl_DString line, command; 
char *cmdStr; 
int code, count; 
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count = Tcl_Gets(chan, &line); 
if (count < 0) { 
handle errors and end of file 


Tcl _ DStringAppend (&command, 


Tcl DStringValue(&line), -1); 
emdStr = Tcl DStringAppend(&command, "\n", -1); 
Tcl _ DStringFree (&line) ; 
if (Tcl_CommandComplete(cmdStr)) { 


Tcl CreateChannelHandler(chan, 0, 
StdinProc, chan); 

code = Tcl Eval(interp, cmdStr); 

Tcl CreateChannelHandler(chan, TCL READABLE, 
StdinProc, chan); 

Tcl _ DStringFree (&command) ; 


} 


After reading from standard input and checking for errors and end of file, 
stdinproc adds the new data to the command buffer’s current contents. Then it 
checks to see if the buffer contains a complete Tcl command (it won’t, for 
example, ifa line such as foreach i sx , has been entered but the body of the 
foreach loop hasn’t yet been typed). If the command is complete, stainproc 
disables the channel handler, evaluates the command, reestablishes the 
handler, clears the dynamic string buffer, and is ready for the next command. 


Note 


It is usually best to use non-blocking I/O with file handlers, just to be 
absolutely sure that I/O operations don’t block. To request non- 
blocking I/O, pass the correct flag bit to 1c1_rsopenrilechanne1, and set the 
async flag tO tcl_opentcpclient, OF USE Tcl setChanneloption to turn off 
blocking. If you use channel handlers for writing to channels with long 
output delays, such as pipes and network sockets, it is essential that 
you use non-blocking I/O; otherwise, if you supply too much data in a 
tcl write Call, the output buffers fill and the operating system puts the 
process to sleep. 


Note 
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For ordinary disk files, you should not use the event-driven approach 
described in this section, because reading and writing these files rarely 
incurs noticeable delays, and operating systems maintain a fiction that 
they never do. Channel handlers are useful primarily for channels such 
as terminals, pipes, and network connections, which can block for 
indefinite periods of time. Unfortunately, with network-based files the 
fiction of immediate action wears rather thin, but operating systems 
still maintain the fiction and only allow you to do blocking waits for 
them. Sometimes abstractions are inevitably incomplete. 


43.3 Timer Events 


Timer events trigger callbacks after particular time intervals. For example, 
entry widgets use timer events to display blinking insertion cursors, and the 
nttp package uses timer events to time out very slow connections. In the case 
of entry widgets, when the entry gains the input focus, it displays the 
insertion cursor and creates a timer callback that triggers in a few tenths of a 
second. The timer callback erases the insertion cursor and reschedules itself 
for a few tenths of a second later. The next time the callback is invoked, it 
turns the insertion cursor on again. This process repeats indefinitely so that 
the cursor blinks on and off. When the widget loses the input focus, it 
cancels the timer callback and erases the insertion cursor. 

The function rc1_createtimerHandler Creates a timer callback: 


Tcl_TimerToken Tcl_CreateTimerHandler(int milliseconds, 
Tel TimerProc *callback, ChentData clientData); 


The miitiseconas argument specifies how many milliseconds should elapse 
before the callback is invoked. 1c1_createtimertandier returns immediately, and 
its return value is a token that can be used to cancel the callback. After the 
given interval has elapsed, Tcl invokes caiipacx, which must match the 
following prototype: 


void Tcl_TimerProc(ClientData clientData); 


Its argument is the clientpata passed tO Tcl_CreateTimerHandler. callback is called 
only once, after which Tcl deletes the callback automatically. If you want 
callback to be called over and over at regular intervals, caiipack should 
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reschedule itself by calling tc1_createrimernandier each time it is invoked. 


Note 


There is no guarantee that caiipack will be invoked at exactly the 
specified time. If the application is busy processing other events at the 
specified time, callback Won't be invoked until the next time the 
application invokes the event dispatcher, as described in Section 43.5. 


The function rc1_peietetimerHandier cancels a timer callback: 


void Tcl DeleteTimerHandler(Tcl_ TimerToken token); 


It takes a single argument, which is a token returned by a previous call to 
Tcl_CreateTimerHandier, and deletes the callback so that it is never invoked. It is 
safe to invoke tc1_peletetimerHandier even If the callback has already been 
invoked; in this case the function has no effect. 


43.4 Idle Callbacks 


The function rc1_pownentaie creates an idle callback: 


void Tcl DoWhenldle(Tcl_IdleProc *callback, 
ClientData clientData); 


This arranges for calipack to be invoked the next time the application 
becomes idle. The application is idle when Tcl’s main event-processing 
function, tc1 poonezvent, 18 Called and no channel events or timer events are 
ready. Normally when this occurs, 1tci_poonervent Suspends the process until 
an event occurs. However, if idle callbacks exist, all of them are invoked. 
Idle callbacks are also invoked when the upaate Tel command is invoked. 
The caiibacx for an idle callback must match the following prototype: 


typedef void Tcl IdleProc(ClientData clientData); 


It returns no result and takes a single argument, which is the ciientpata 
argument passed to tc1_powhentdle. 

Tcl CancelIdlecall deletes an idle callback so that it won’t be invoked after 
all: 
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void Tcl_CancelldleCall(Tcl_IdleProc *callback, 
ClientData clientData); 


Tcl Cancelidiecall deletes all of the idle callbacks that match caiipack and 
clientbata (there can be more than one). If there are no matching idle 
callbacks, the function has no effect. 

Idle callbacks are used heavily to implement the delayed operations 
described in Section 29.3. The most common uses of idle callbacks in Tk 
are for widget redisplay and geometry recalculation. This is because it is 
generally a bad idea to redisplay a widget immediately when its state is 
modified, since this can result in multiple redisplays when related 
modifications happen together. For example, suppose the following Tcl 
commands are invoked to change a label widget .1: 


.l configure -background purple -textvariable msg 
set msg "Hello, world!" 
.l configure -bd 3m 


Each of these commands modifies the widget in a way that requires it to be 
redisplayed, but it would be a bad idea for each command to redraw the 
widget. This would result in three redisplays, which are unnecessary and 
can cause the widget to flash as it steps through a series of changes. It is 
much better to wait until all of the commands have been executed and then 
redisplay the widget once. Idle callbacks provide a way of knowing when 
all available events have been fully processed. 


43.5 Invoking the Event Dispatcher 


The preceding sections described the first two parts of event management: 
creating event handlers and writing callback functions. The final part of 
event management is invoking the Tcl event dispatcher, which waits for 
events to occur and invokes the appropriate callbacks. If you don’t invoke 
the dispatcher, no events are processed and no callbacks are invoked. 

Tcl provides one function for event dispatching, tc1 poonezvent, and Tk 
provides another, tx maintoop. Tk applications normally use rx maintoop, and 
non-Tk applications always use tci_poonezvent, usually within some kind of 
loop. 


Note 
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Tcl applications can install a main-loop function into Tcl with tc1_ 
SetMainLoop. Tcl_Main Calls the installed main-loop function after the initial 
startup script (1.e., the script file specified on the command line) has 
been executed. Tk installs 1 maintoop aS a main-loop function by 
default; if you want to use a custom main-loop function but also use Tk, 
make sure you install your function only after the Tk package 1s loaded. 


Tk MainLoop takes no arguments and returns no result; it is typically invoked 
once, in the main program after initialization. rx maintoop calls the Tcl event 
dispatcher repeatedly to process events. When all available events have 
been processed, it suspends the thread until more events occur, and it 
repeats this over and over. It returns only when every Tk window created by 
the thread has been destroyed (for example, after the aestroy . command has 
been executed). A typical main program for a Tk application creates a Tcl 
interpreter, creates the main Tk window and application, performs some 
other application-specific initialization (such as evaluating a Tcl script to 
create the application’s interface), and then calls rx maintoop. When rx mMaintoop 
returns, the main program exits. Thus Tk provides top-level control over the 
application’s execution, and all of the application’s useful work 1s carried 
out by event handlers invoked via tx maintoop. 

The other function for event dispatching 1s tci_poonervent, which provides a 
lower-level interface to the event dispatcher: 


int Tcl DoOneEvent(int flags) 


The riags argument is normally o (or, equivalently, tct_att_svenrs). In this case 
Tcl_DoOneEvent Processes a single event and then returns :. If no events are 
pending, tc1_poonervent Suspends the thread until an event arrives, processes 
that event, and then returns :. 

For example, tx maintoop 1s implemented using tc1_Doonezvent:! 


void Tk_MainLoop(void) { 
while (/* Number of main windows > 0 */) { 
Tcl_DoOneEvent (0) ; 
} 


} 


AS you Can See, Tk Maintoop just calls rx poonezvent Over and over until all the 
main windows have been deleted. 

Tk DoOneEvent 18 also used by commands such as wwait and txwait that want to 
process events while waiting for something to happen. For example, the 
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vwait Command processes events until a given variable is updated, then it 
returns. Here is the C code that implements this command: 


int done; 


Tcl _TraceVar(interp, nameString, 
TCL_GLOBAL_ONLY|TCL_TRACE_WRITES|TCL_TRACE_UNSETS, 
VwaitVarProc, &done) ; 

done = 0; 

while (!done) { 

Tel_DoOneEvent (0) ; 

} 


Tcl_UntraceVar(interp, nameString, 
TCL_GLOBAL_ONLY|TCL_TRACE_WRITES|TCL_TRACE_UNSETS, 
VwaitVarProc, &done) ; 


The variable namestring identifies the variable whose update is awaited. The 
code creates a trace callback that is invoked when the variable is updated, 
then invokes tc1_poonezvent Over and over until the done flag is set to indicate 
that the variable has been set or deleted. The callback for the variable trace 
is as follows: 


char *VwaitVarProc(ClientData clientData, 
Tcl Interp *interp, const char *namel, 
const char *name2, int flags) 


int *donePtr = clientData; | 


*donePtr = 1; 
return NULL; 


} 


The ciientpata argument is a pointer to the flag variable. vwaitvarproc 18 only 
ever called in the situation that it has been set to detect, so all it has to do is 
set the flag variable to 1 when it is called. 

The ¢1ags argument to tc1_poonezvent Can be used to restrict the kinds of events 


it considers. If it contains any of the bits TCL FILE EVENTS, TCL TIMER EVENTS, OF 
TcL_tpLe events, Only the events indicated by the specified bits are considered. 
Furthermore, if the siags argument includes the bit vc. _ponr wart, or if neither 
file events nor timer events are selected, tc1 poonervent doesn’t suspend the 
thread if no event is ready to be processed. Instead, it returns immediately 
with a o result to indicate that it had nothing to do. For example, the upaate 


idletasks Command 1s implemented with the following code: 
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2. Tk’s X events are implemented as rct _rttz events in the lowest levels of 
the event dispatcher by directly observing the communication channel that 
the X library uses to communicate with the X server. This is fairly tricky 
code, but it allows the user of Tk, even as a C library, to ignore the details. 


while (Tcl _DoOneEvent (TCL IDLE EVENTS) != 0) { 
/* empty loop body */ 
} 


By comparison, the core of the normal upaate command is this code: 


while (Tcl_DoOneEvent (TCL ALL EVENTS|TCL DONT WAIT)) { 
/* empty loop body */ 
} 
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44. File System Interaction 


Tcl provides a platform-independent C API for working with files and 
directories. Using these functions instead of platform-native system calls 
makes your code more portable. The Tcl API also automatically handles any 
translation required between the Tcl-native UTF representation of character 
strings and the system encoding; all input and output string parameters for 
these functions are based on Tel-native UTF-encoded strings. Furthermore, 
the Tcl API automatically supports Tcl’s virtual file systems. If the paths you 
provide as parameters to these functions represent locations in a virtual file 
system that your application has mounted (for example, a ZIP archive or an 
FTP site), the functions can access the files as though they were typical on- 
disk file systems. 


Note 


Most of these functions have an equivalent Tcl command at the 
scripting level. In general, consider using a Tcl script if possible when 
interacting with the file system, as it is faster to develop and easier to 
modify in the future, should it prove necessary. These C-level functions 
are most appropriate for performing occasional file system operations 
when doing significant development in C. 


44.1 Tcl File System Functions 


Table 44.1 lists the functions provided for file system access and their 
equivalent scripting-level commands. You can find more details about them 
in Tcl’s riiesystem.3 reference documentation. Most of these functions return o 
on success or -1 on failure and set errno to describe the reason for failure. 
Additionally, Tcl’s file system API is based almost completely on Tel 
objects. Some functions may cache internal representations and other path- 
related strings, so objects that you pass to these functions must have a 
reference count greater than 0, for example: 
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Tcl_Obj *fileName = 


Tcl _NewStringObj ("/tmp/foobar", -1); 


Tel_IncrRefCount (fileName) ; 


ret = 


Tcl_DecrRefCount (fileName) ; 


Table 44.1 Tcl C Functions and Equivalent Tcl Commands for File System 


C function 
Tcl_FSAccess 


Tcl_FSChdir 
Tcl_FSCopyDirectory 
Tcl_FSCopyFile 
Tcl_FSCreateDirectory 
Tcl_FSEvalFile 
Tcl_FSFileAttrsGet 
Tcl_FSFileAttrsSet 
Tcl _FSFileAttrStrings 
Tcl_FSFileSystemInfo 
Tcl_FSGetCwd 
Tcl_FSGetNormalizedPath 
Tel_FSGetPathType 


Tcl_FSDeleteFile (fileName) ; 


Interaction 
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Equivalent Tcl command 


file readable 
file writable 
cd 

file copy 


file mkdir 
source 


file attributes 


file system 
pwd 
file normalize 


file pathtype 


Tcl FSJoinPath file join 
Tcl FSJoinToPath 
Tcl _FSLink file link 


file readlink 


Tcl _FSListVolumes file volumes 
Tcl _ FSLoadFile load 

Tcl FSLstat file istat 
‘Tol_FSMatchInDirectory glob 

Tel FSOpenFileChannel open 
Tcl_FSPathSeparator file separator 
Tcl FSRemoveDirectory file delete 
Tcl FSDeleteFile 

Tcl_FSRenameFile file rename 
Tcl _FSSplitPath file split 
Tcl_FSStat file stat 

Tcl_ FSUtime file mtime 

Tcl _ TranslateFileName file nativename 


If a function returns an object, you should assume that the reference count is 
0. As with any other newly created Tcl object, if you use the object 
elsewhere, you might need to call tc1_tncrrefcount on the object to make sure 
that it isn’t freed accidentally in the wrong place. See Chapter 32 for more 
information on managing the reference counts of Tcl objects. 


44.2 Virtual File Systems 


Another interesting aspect of the Tcl file system interaction implementation 
is that it 1s built on top of a “virtual file system” that is accessible via Tcl’s 
C API. In other words, it is possible to write new “file systems” that Tcl 
then accesses as if they were regular files. Some examples of this are 
archive files, such as ZIP and tar, and remote files—WebDAV, FTP, and 
HTTP. When you “mount” a ZIP file with the appropriate extension, you can 
ca Inside it, open files, use giob, and even source Tel files inside it, all as if it 
were just a part of the disk in which Tcl resides. Chapter 11 discusses how 
you can use the tcives extension to mount and access such virtual file systems 
in your applications. 

Detailed coverage of the process of implementing a new virtual file system 
is beyond the scope of this book and may be found in Tcl’s excellent 
reference documentation—specifically, the ritesystem.3 reference page. The 


812 


basic process is similar to that covered in Chapter 42 for implementing 
custom channel types: you create a structure and set its fields to functions 
that carry out the underlying actions of the specific operations described in 
this chapter. 
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45. Operating System Utilities 


Tcl provides a variety of functions to deal with underlying operating system 
services. This layer is platform-independent, except where it makes sense to 
give the user access to lower-level options that may not be present on all 
platforms. 


45.1 Functions Presented in This Chapter 


This chapter discusses the following functions for accessing operating 
system services: 

® Tcl Channel Tcl OpenCommandChannel (Tcl _Interp *interp, 

int argc, CONST char *argv, int flags) 

Opens a command channel using argv as the command and its arguments. 

® Tcl DetachPids (int numPids, int *pidPtr) 
Gives Tcl responsibility for numpias child processes that are passed in via the 
pidptr array. 

® Tcl ReapDetachedProcs () 
Invokes the waitpia system call on each background process so that its state 
can be cleaned up if it has exited. If the process hasn’t exited yet, 
Tcl_ReapDetachedProcs doesn’t wait for it to exit. 

* Tcl Pid Tcl WaitPid(int pid, int *statPtr, int options) 
Wrapper for the waitpia system call. 


Tcl AsyncHandler Tcl AsyncCreate(Tcl_ AsyncProc * func, 
ClientData clientData) 

Creates an asynchronous handler, which is able to interrupt Tcl execution, 

and returns a token for it. 


- Tcl AsyncDelete (Tcl AsyncHandler async) 


Deletes an asynchronous handler, given a token. 


Tcl AsyncMark (Tcl AsyncHandler async) 
Marks the asynchronous handler indicated by async as ready to run. 
int Tcl AsyncInvoke(Tcl_Interp *interp, int code) 


Calls all handlers that are ready. 
* int Tcl AsyncReady() 
Checks to see if any handlers are ready to be run. 


® CONST char *Tcl_ Signalid(int sig) 
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Returns a machine-readable string describing the signal, such as steprps. 
® CONST char *Tcl SignalMsg (int sig) 
Returns a human-readable string describing the signal, such as bus error. 


® Tcl Exit (int status) 


Exits Tcl and the process. 


Tcl Finalize () 
Similar to tci exit, but only ends the use of Tcl; it does not terminate the 
entire process. 


= Tcl CreateExitHandler (Tcl ExitProc proc, 
ClientData clientData) 
Creates a handler to be called when tc1 exit OF tcl Finalize 18 called. 


* Tcl DeleteExitHandler (Tcl ExitProc proc, 


ClientData clientData) 

Deletes an exit handler created by tc1_createrxitHandler. 

® CONST char* Tcl GetHostName () 
Returns a pointer to a string containing the current host name. 

® Tcl GetTime(Tcl Time *timePtr) 
Fills in the previously allocated timerer structure, which contains the number 
of seconds since the epoch and the number of microseconds since the last 
second. 


® int Tcl PutEnv(const char *assignment) 


Given an assignment String in the form wame-vaiue, Sets an environment variable. 


45.2 Processes 


The ci _opencommandchanne1 function spawns a process external to Tcl—the 
equivalent of evaluating an exec OF open | command. This is another case 
where it typically makes sense to write Tcl code instead of C code if 
possible, because the functionality is virtually identical, and writing Tcl 
code is much faster. Its syntax 1s 


Tcl Channel Tcl OpenCommandChanneli ( 
Tcl Interp *interp, int argc, 
CONST char **argv, int flags); 


argc 18 the number of arguments passed to the command or commands, via 
the array of strings argv. argviargc] Must be nuit, so be sure to make argv one 
element larger than argc. Keep in mind that it is possible to launch a 
pipelined sequence of commands such as is, |, grep, and foo, and that 
standard exec arguments (see Chapter 12) like >, <, «, and so on are also valid 
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elements of argv. The channel returned is affected by an ORed combination 
of the following flags: 

* TCL STDIN 
The newly created channel is attached to the standard input of the first 
process in the sequence launched by ci opencommandchanne1. In other words, 
data written to the channel is sent as input to the process. If this flag is not 
set, the first process uses the current (calling) process’s standard input. 

° TCL STDOUT 
The newly created channel is attached to the standard output of the last 
process launched by tc1_opencommanachanne1. Reading from the channel returns 
data from the last process created. If this flag is not set, the last process’s 
standard output goes to the standard output of the (current) calling process. 

° TCL STDERR 
Data written to the standard error channel by any process spawned by 
Tcl_OpenCommandChannel 1$ directed to the channel for reading. When the channel 
is closed, if there is data in the standard error channel, an error is raised. If 
this flag is not set, the standard error data goes to the standard error of the 
(current) calling process. 

® TCL ENFORCE MODE 
This flag, when it is set, means that standard exec arguments such as < and > 
cannot override the rct_stprn, rc._stpour, and tcL_stprrr flags; an error is raised 
if redirections are attempted. 


Note 


The newly created channel is not registered with the supplied 
interpreter. See Chapter 42 for information on registering channels. 


In the following example we create a subtci1 command, which pipes a script 
into a tcisn that is launched as a subprocess and then returns the output: 
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static int 
SubTclCmd(ClientData clientData, Tcl_Interp *interp, 
int objc, Tcl_Obj *CONST objv[]) { 
Tcl_Obj *out; 
CONST char **argv; 
Tcl_Channel chan; 
int arge = 1; 
static char *argvO = NULL; 


if (objec != 2) { 
Tcl_WrongNumArgs(interp, 1, objv, "script"); 
return TCL_ERROR; 

} 

if (argvO == NULL) { 
Tcl_Eval(interp, "info nameofexecutable") ; 
argvO = strdup(Tcl_GetStringResult (interp) ) ; 


out = Tcl_NewObj(); 

argv = (CONST char **)ckalloc(sizeof(char *) * 2); 

argv[0] = argv0; 

argv[1] = NULL; 

chan = Tcl_OpenCommandChannel ( 
interp, argc, argv, 
TCL_STDOUT|TCL_STDIN|TCL_STDERR) ; 

ckfree((char *)argv); 


if (chan == NULL) { 
return TCL_ERROR; 
} 


if (Tcel_WriteObj (chan, objv[1]) < 0) { 
return TCL_ERROR; 
} 


if (Tcl_Flush(chan) != TCL_OK) { 
return TCL_ERROR; 


if (Tcl_ReadChars(chan, out, -1, 0) < 0) { 
return TCL ERROR; 


if (Tcl_Close(interp, chan) != TCL_OK) { 
return TCL_ERROR; 
} 


Tcl_SetObjResult (interp, out); 
return TCL_OK; 
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We construct the command in argv, then pass it to tc1_opencommanachannel. The 
subprocess is able to read the input because we set the rc srprn flag and 
then send opjvii) to the channel with 1c1 writeobj, followed by a flush 
operation to make sure that the data has arrived. Thanks to the tc1_srpour flag, 
the subprocess returns its results to chan, where we subsequently read them 
and return them as the result of the command. The sustc1 command is called 
from Tcl like so: 


set result [subtcl { 
puts hello 
exit 


}] 


The subtc1 command returns any output from the tcisn process it spawns. One 
improvement that could be made to this example would be to involve the 
event loop so that the calling process would not block while waiting for the 
subprocess to finish. 


45.3 Reaping Child Processes 


Tcl _OpenCommandchannel 18 Sufficient to manage the lifetime of external 
processes. However, if you wish to launch external processes yourself, such 
as by using the fork and exec system calls, you can still manage them from 
Tel. 

If an application creates a subprocess and abandons it (1.e., the parent never 
invokes a system call to wait for the child to exit), the child executes in 
background, and when it exits it becomes a zombie. It remains a zombie 
until its parent officially waits for it or until the parent exits. Zombie 
processes occupy space in the system’s process table, so if you create 
enough of them, you can overflow the process table and make it impossible 
for anyone to create more processes. To keep this from happening, you must 
invoke a system call such as wait OF waitpia, Which returns the exit status of 
the zombie process. Once the status has been returned, the zombie 
relinquishes its slot in the process table. This procedure 1s often referred to 
as reaping the child processes. 

The tci_petachpias function notifies Tcl to take responsibility for reaping one 
or more child processes: 


Tcl_DetachPids(int numPids, int *pidP tr); 
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The piartr argument is an array of process identifiers, and numpias 1s the 
number of identifiers in the array. Each of these processes now becomes the 
property of Tcl, and the caller should not refer to them again. 

To reap these child processes, you call 1c1_ReappetacheaProcs, Which takes care 
of the low-level work of cleaning up after any processes that have exited. If 
some of the detached processes are still executing, 1c1_ReappetachedProcs 
doesn’t actually wait for them to exit; it cleans up only the processes that 
have already exited and returns. 

Should it prove useful to wait on one particular child process, the tci_waitpia 
function, a wrapper for the waitpia system call, is the right tool for the job: 


Tcl Pid Tcl_ WaitPid(int pid, int *statPtr, int options); 


The pia argument is the process identifier, and statrtr 1s a pointer to an 
integer that the function sets to either o or =cut to indicate the status of the 
child process. The options permitted depend on the underlying operating 
system, but wvoxanc should indicate that the function should return 
immediately, rather than block, if the child has not exited. 


45.4 Asynchronous Events 


Tcl does not provide commands for handling ANSI or POSIX signals 
(though you can use an extension such as TclX or Expect if you need this 
functionality), but it does provide a generic framework for dealing with 
asynchronous events like signals. The central concept in this infrastructure 
is that when a signal (or some other event) arrives, it should not interrupt 
Tcl while Tcl is busy. For instance, if a signal arrives and you attempt to 
perform an evai while Tcl is already performing that command, instability 
could result. Instead, Tcl is notified that an event of interest has occurred via 
a flag, and when Tcl is able to, it processes the event. 

The following example demonstrates an extremely simple signal handler: 
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#include <tcl.h> 
#include <signal.h> 


static Tcl_AsyncHandler SignalHandler = NULL; 
static int sigs = 0; /* Number of signals received. */ 


int Signals Init(Tcl_Interp *interp) { 


#ifdef USE_TCL_STUBS 
if (Tcl_InitStubs(interp, "8", 0) == NULL) { 
return TCL_ERROR; 
} 


#endif 


Tcl SetVar2Ex(interp, "::counter", NULL, 
Tcl_NewIntObj (0), 0); 


SignalHandler = Tcl AsyncCreate(HandleSignals, 
(ClientData)interp) ; 

Signal (SIGHUP, lowlevelhandler) ; 

signal(SIGINT, lowlevelhandler) ; 


if (Tcl_PkgProvide(interp, "signals", "0.1") != TCL_OK) { 
return TCL ERROR; 
} 


return TCL OK; 


} 


This code uses the ci asynccreate function to register a ci AsyncHandler 
function named sandiesignais. The return value is a unique token to identify 
the handler. As is discussed below, an interpreter is not always available to 
asynchronous handlers, so we pass the current interpreter to it as client data. 
This carries some risk, in that the interpreter might be deleted before the 
handler is called, but for the sake of our example, we assume this is not the 
case. The next two lines initialize signal handlers for stcsve (hangup) and 
stcrnt (interrupt), which use this function: 


void lowlevelhandler(int signum) { 
Sigs++; 
Tcl AsyncMark (SignalHandler) ; 


} 


The 1owlevelhandier function simply increments the tally of received signals in 
a global variable and then invokes 11 asyncmarx to tell Tcl that signainanaier’s 
callback is ready for action. When Tcl reaches a point in its execution 
where it is able to process the asynchronous event, it calls the sanaiesignais 
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function: 


static int 
HandleSignals(ClientData clientData, 
Tcl_Interp *interp, int code) { 
int i = 0; 
int counterVal = 0; 
Tcl Obj *counterObj; 
if (interp == NULL) { 
interp = (Tcl_Interp *)clientData; 
if (interp == NULL) { 
/* It's deleted, can't do anything useful. */ 
return TCL ERROR; 


} 


counterObj = Tcl GetVar2Ex(interp, "::counter", NULL, 0); 
Tcl GetIntFromObj (interp, counterObj, &counterVal) ; 
while (sigs) { 
Tcl SetVar2Ex(interp, "::counter", NULL, 
Tcl_NewIntObj (counterVal+1), 0); 
i++; 
sigs--; 
} 


return code; 


} 


The first argument to the signal handler corresponds to the ctientpata 
argument of the tci asynccreate function and, as in other Tcl subsystems, 
serves as a means to pass data to the function called by the asynchronous 
handler. If the handler is invoked just after an interpreter completes 
execution of a command, the interp argument identifies the interpreter in 
which the command was evaluated, and code is the completion code returned 
by that command. (The command’s result is present in the interpreter’s 
result.) When the handler returns, whatever it leaves in the interpreter’s 
result is returned as the result of the command, and the integer return value 
of the handler is the new completion code for the command. On the other 
hand, if Tcl is in the event loop or in other states where no interpreter is 
active, interp 1S nutn and code 18 0, and the return value from the handler is 
ignored. 


Note 


It is almost always a bad idea for an asynchronous event handler to 


822 


modify the interpreter’s result or return a code different from its code 
argument. This sort of behavior can disrupt the execution of scripts in 
subtle ways and result in bugs that are extremely difficult to track 
down. If an asynchronous event handler needs to evaluate Tcl scripts, it 
should first save the interpreter’s state by calling 1c1 savetnterpstate, 
passing in the code argument. When the asynchronous handler is 
finished, it should restore the interpreter’s state by calling 
Tcl_RestoreInterpstate and then returning the code argument. 


In this simple example, we first attempt to obtain a valid interpreter, 
returning an error condition if we don’t have one. Then we increment a 
counter variable for each signal that has arrived. 


Note 


Even in cases where the handler receives an active interpreter as an 
argument, there are no guarantees as to which interpreter it is, if 
several are active, or in what sort of state it is. Thus, it is 
recommended that you do not attempt to do too much even in this 
handler. One possible solution would be to make asynchronous events 
into an event source for Tcl’s event loop. See Chapter 42 for more 
information. 


45.5 Signal Names 


On the topic of signals, Tcl also provides two functions that let you 
transform a signal number into something more readable. Both rc1_signaita 
and tc1_signaimsg take a POSIX signal number as argument, and each returns a 
string describing the signal. tc1_ signaiza returns the official POSIX name for 
the signal as defined in signai.n, and 1c1_signaimsg returns a human-readable 
message describing the signal. For example, 


Tel_Signalld(SIGALRM) 
returns the string stcateu, and 


Tcl SignaIMsg(SIGALRM) 
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returns atarm clock. 


45.6 Exiting and Cleanup 


The tci_exit function call is provided to cleanly exit a process. It is 
equivalent to the exit command in Tcl. Never call the C exit function 
directly; Tcl provides a callback mechanism for exit handlers via 
Tcl _CreateExitHandler. Tcl_ Exit ensures that the proper cleanup is performed, 
whereas simply calling exit may skip that step. Like other callbacks, this one 
takes a function as an argument: 


static void 
OnExit (ClientData clientData) { 

fprintf(stderr, "We are down for the count\n"); 
} 


Tcl CreateExitHandler(OnExit, NULL) ; 


It is possible to provide a ciientpata value that is passed to the exit handler. 
This could be used to cleanly shut down any communications with other 
systems, networked resources such as a database server, connected clients, 
and so forth. You can delete an existing exit handler with the 
Tcl DeleteExitHandler function. 

Should you wish only to clean up Tcl in your program and continue running, 
instead of shutting down the whole process, the tc1 Finalize function carries 
out the necessary work. This call should also be used prior to unloading, if 
Tcl was loaded into your application as part of a shared object (.so or .ai1) 
that at some point may be unloaded. Most applications load modules but do 
not unload them, so this is not a very common occurrence. 


Note 


If you are writing a multithreaded Tcl application, there are analogous 
functions for exiting a thread, terminating the use of Tcl within a 
specific thread, and registering thread exit handlers. See Chapter 46 
for more information. 


824 


45.7 Miscellaneous 


The tci_cetHostName function returns a string that contains the host name for the 
machine on which Tel is running. The storage allocated belongs to Tcl, and 


you should 
The Tcl Put 


not attempt to free it. 
env function is meant to be a replacement for the putenv system 


call. It takes a string argument of the form varwamz-value. Remember that it is 
also possible to work with environmental variables via Tel’s global env 
array, USINg tc1_setvar and the like. 

To obtain information about the current time, Tcl provides the ci cetrime 
function, which retrieves a structure consisting of two long integers: the 
current time in seconds since January 1, 1970, 00:00 UTC epoch, and the 


number of 
second; for 


microseconds that have elapsed since the start of the current 
example: 


Tcl_ Time timePtr; 


Tcl _GetTime (&timePtr) ; 
printf ("seconds tld\n", timePtr.sec) ; 
printf ("microseconds %ld\n", timePtr.usec) ; 
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46. Threads 


This chapter covers the use of Tcl’s thread API from C and the use of Tel in 
threaded programs. Complex programming with threads is tricky and can 
lead to difficult-to-find errors if not treated with caution. We discuss Tcl’s 
API but do not cover the nuances of programming with threads. For a 
thorough discussion of the topic, refer to books such as Programming with 
POSIX Threads by David Butenhof (ISBN 0-201-63392-2). 


46.1 Functions Presented in This Chapter 


This chapter discusses the following functions related to thread management 
in Tcl: 
® int Tcl CreateThread(Tcl_ ThreadId *idPtr, 
Tcl _ThreadCreateProc threadProc, 
ClientData clientData, int stackSize, int flags) 
Creates a new thread whose new ID 1s stored in iarer and starts running in 
the function threaaproc. See the text and the reference documentation for 
information on the stacksize and riags arguments. 
® Tcl _ExitThread(int status) 


Terminates the current thread and invokes per-thread exit handlers. 


Tcl FinalizeThread() 
Cleans up per-thread Tcl state and calls thread exit handlers without 
actually terminating the thread. 


bd Tcl CreateThreadExitHandler (Tcl ExitProc proc, 


ClientData clientData) 


Registers a per-thread exit handler proc that is called with c1ientpata. 


$ Tcl DeleteThreadExitHandler (Tcl ExitProc proc, 
ClientData clientData) 
Deletes a per-thread exit handler. 
® int Tcl _JoinThread(Tcl_ThreadId id, int result) 
Waits on the exit of a thread that has been marked joinable via the 
TcL_ THREAD JornasLeE flag tO tci_createThreaa. Attempting to wait on a non- 
joinable thread returns an error. 


* void *Tcl_GetThreadData (Tcl ThreadDataKey *keyPtr, 


int *size) 
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Returns a pointer to a block of thread-private data. Its argument is a key that 
is shared by all threads and a size for the block of storage. The storage is 
automatically allocated and initialized to all zeros the first time each thread 
asks for it. The storage is deallocated automatically by tc1_Finalizethreaa. 

® TCL DECLARE MUTEX (mutexName) 
Macro to declare mutexes in a portable way. Has no effect if threads are not 
enabled. 

® void Tcl _MutexLock(Tcl_Mutex *mutexPtr) 
Locks a mutex, waiting until it’s unlocked if some other thread holds the 
lock. 


void Tcl MutexUnlock (Tcl Mutex *mutexPtr) 


Unlocks a mutex. 


® void Tcl MutexFinalize (Tcl Mutex *mutexPtr) 


Frees any resources associated with a mutex after it is no longer needed. 


® void Tcl ConditionNotify (Tcl Condition *condPtr) 


Unblocks threads waiting on the condition variable. 


void Tcl ConditionWait (Tcl Condition *condPtr, 

Tcl Mutex *mutexPtr, Tcl_Time *timePtr) 
Waits for the condition in conartr to be notified. Returns with mtexrer locked. 
If timertr 18 not nozt, waits only the specified time for the condition to be 
notified. 


© void Tcl ConditionFinalize(Tcl_ Condition *condPtr) 


Frees any resources associated with a condition after it is no longer needed. 


46.2 Thread Safety 


Tel is thread-safe, meaning that it’s possible to use it within multithreaded 
programs without problems. However, Tcl interpreters must be confined to 
and accessed by only one thread, the thread where the interpreter was 
created. This means that you cannot create an interpreter and share it among 
several threads. 


46.3 Building Threaded Tel 


Currently, most distributions of Tcl are built with threads enabled. You can 
check by testing for the existence of ::tci piatform(threadea) IN your 
interpreter. If you are building Tcl yourself, you must enable a threaded 
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build by running the ./configure script with --cnabie-threaas at build time. See 
Chapter 47 on building Tcl for more information. If you have a threaded Tcl, 
keep in mind that you should also build any extensions you use with --enabie- 
threads aS Well. 


46.4 Creating Threads 


New threads are created via the cross-platform 1ci createthreaa function, 
which has the following signature: 


int Tcl _CreateThread(Tcl_ThreadId *idPtr, 
Tcl_ThreadCreateProc threadProc, 
ClientData clientData, 
int stackSize, int flags); 


The iaper is a pointer to an integer where the thread ID of the newly created 
thread is stored. When the operating system creates the new thread, it starts 
running in the threaaproc function, with ciientpata as its only argument. It is 
possible to set the stack size for the new thread, but it is recommended to 
simply use the rct_rsreap stack pzraut Macro to let the operating system use 
the standard stack size. Currently, fiags may be either cc. rxreap noriacs, 
which specifies default behavior, or tct_tHrzap_gornas.e, Which means that the 
new thread is joinable. 

A thread is joinable if a second thread can wait for it to exit. Tcl provides 
the tc1_sointhreaa function to accomplish this task. It takes two arguments: the 
Tcl_Threaatp Of the thread to join and a pointer to an integer where the exit 
code for the joined thread is stored. The tc1_gointnreaa function blocks until 
the specified thread exits. Trying to wait on a non-joinable thread or a 
thread that is already waited upon results in an error. Waiting for a joinable 
thread that has already exited is possible; the system retains the necessary 
information until after the call to 1c1 sointhreaa. This means that not calling 
Tcl_Jointhreaa for a joinable thread causes a memory leak. 


Note 


Windows does not currently support joinable threads. Therefore, the 
Tcl _Jointhread function is not supported on that platform, and the 
TCL THREAD JOINABLE flag tO Tcl_CreateThread 1S ignored. 
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46.5 Terminating Threads 


Tel provides the tci_sxitthreaa function to terminate the current thread. As 
part of the termination process, Tcl deletes all interpreters and other Tcl 
resources associated with the thread. You also have the option of registered 
exit handlers for the thread using the tc1_createzxitHandier function. The exit 
handlers can do anything that you like on thread termination, such as flushing 
buffers and freeing global memory. 

Tcl also provides a tci Finalizethreaad function, which deletes the Tcl 
interpreters and other resources for the thread and invokes the thread exit 
handlers but does not terminate the thread. Note that tc1 exittnreaa calls 
Tcl _FinalizeThreaa aS part of its operation, so there’s no need for you to do so 
explicitly. 


46.6 Mutexes 


A mutex (short for mutual exclusion) is used to limit access to a portion of 
code to one thread at a time. If you have a section of code that must execute 
“atomically’—you don’t want it to be interrupted or performed by more 
than one thread at a time—a mutex is most likely what you need to use. Tcl 
has a platform-independent macro for creating a mutex: 


TCL_DECLARE_MUTEX(myMutex); 


The macro also ensures correct mutex handling even when the core is 
compiled without threads enabled. 

Once you have created a mutex, you can use tc1 Mutextock and tc1_mtexUniock 
to protect critical sections of your code: 


Tcl MutexLock (&myMutex) ; 
f* ono Crattiieal section<..0 */ 
Tcl _ MutexUnlock (&myMutex) ; 


These functions have no effect if Tcl is not compiled with threads. For a 
threaded application, if one thread locks a mutex, any other thread that 
attempts to lock it waits (blocks) until the first thread unlocks it. This means 
that you'll suffer a performance hit if code that 1s frequently executed is 
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protected by mutexes (although that is certainly preferable to data 
corruption!), so try to structure your code in such a way that you don’t need 
to share many resources. The tc1_mutexrinalize function frees the resources 
associated with a mutex when it is no longer needed. 


46.7 Condition Variables 


Condition variables (also known simply as conditions) are another 
common tool in multithreaded programming. They are used when one thread 
needs to let another know something about the state of a shared resource. 
Condition variables are used in conjunction with a mutex to guard the 
shared resource. Before a thread waits on the condition variable, it must 
first lock the mutex guarding the shared resource. Then it calls 
Tcl Conditionwait to wait for notification from another thread; this also 
atomically unlocks the mutex. The thread that performs the notification locks 
the mutex, then calls tc1_conditionnotity to notify the waiting thread(s). Once it 
unlocks the mutex, the tci_conditionwait function in the waiting thread finally 
returns, causing it to “wake up.” Upon return, tc1 conaitionwait automatically 
locks the related mutex for the thread that received the notification. 

Tcl _Conditionwait takes as arguments a pointer to a tc1 condition Structure, a 
pointer to a mutex, and a time value that tells Tcl how long to wait on the 
condition before giving up, or to wait forever if its value is nuit. The 
Tcl_ConditionNotify function takes a pointer to a ‘cl condition aS Its only 
argument. The resources used by a tc1 condition may be freed by calling 
Tcl_ConditionFinalize When the condition is no longer needed. 

A complication arises in that the waiting thread might receive spurious 
“Wwake-ups.” This is common when you have multiple worker threads 
waiting on a condition variable for a shared resource like a message queue. 
When the notification occurs signaling the arrival of a message, the first 
thread that resumes processes the message. When the other worker threads 
get the opportunity to respond to the notification, the message has already 
been consumed, and so there’s nothing for them to do. In these cases, the 
actual call to tc1 conditionwait 1§ usually done within a loop that checks the 
state of the shared resource when tc1_conaitionwait returns and calls it again if 
it needs to wait again. 

As an example from Tcl itself, taken from the rci_tnitnotifier function, here is 
how Tel goes about setting up the notifier thread that the threaded version of 
Tcl uses for its event loop: 
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/* Tcl_InitNotifier: */ 


Tcl_MutexLock (&notifierMutex) ; 
if (notifierCount == 0) { 
if (TclpThreadCreate (a&notifierThread, 
NotifierThreadProc, NULL, 
TCL_THREAD_STACK_DEFAULT, 
TCL_THREAD_NOFLAGS) != TCL_OK) { 
Tcl _Panic("Tcl_InitNotifier: unable to start notifier thread") ; 


} 
} 


notifierCount++; 


/* 
* Wait for the notifier pipe to be created. 
*/ 
while (triggerPipe < 0) { 
Tcl _ ConditionWait (&notifierCv, &notifierMutex, NULL) ; 
} 


Tcl_MutexUnlock (&notifierMutex) ; 


/* NotifierThreadProc: */ 


Tcl_MutexLock (&notifierMutex) ; 
triggerPipe = fds[1]; 


/* 
* Signal any threads that are waiting. 


*/ 


Tcl_ConditionNotify (&notifiercv) ; 
Tcl_MutexUnlock (&notifierMutex) ; 


In this code, Tel first locks the notitiermtex. If no notifiers exist, it then 
launches a notifier thread via the private, internal rciprnreadcreate function. 
This new thread proceeds until it hits a vc1_mutextock(snotifierMutex), Where it 
waits. The first thread continues on, executing the tc1 conditionwait, Which has 
the side effect of unlocking the notiriermtex, allowing the second thread to 
continue, which it does until it executes a cl conditionnotify and 
Tcl_MutexUnlock, returning control to the first thread again, which unlocks the 
mutex for the last time and goes on about its business. As you can see, 
programming with threads is complicated indeed! 


46.8 Miscellaneous 
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To retrieve the thread ID of the current thread, use this function: 
Tcl_ThreadId Tcl_GetCurrentThread(); 


To fetch storage space that can be used for per-thread data, use 


Tcl GetThreadData: 


void *Tcl_GetThreadData(Tcl ThreadDataKey *keyPrr, 
int *size) 


The function returns a pointer to a block of thread-private data. Its argument 
is a key that is shared by all threads and a size for the block of storage. The 
storage is automatically allocated and initialized to all zeros the first time 
each thread asks for it. It is in some ways similar to tc1_aiioc, but try not to 
use it if you don’t need to. The storage space allocated is reclaimed by 
Tcl_FinalizeThreaa Only when the thread exits. 

Tel’s own use Of tc1_GetThreaapata 1N the ThreadsafeLocaltime function (written by 
Kevin Kenny) is instructive. The key, tmxey, is declared static to the file: 
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static Tcl_ThreadDataKey tmKey; 


/* And then, in the ThreadSafeLocalTime function: */ 


static struct tm * 
ThreadSafeLocalTime (timePtr) 
CONST time_t *timePtr; /* Pointer to the number of 
seconds since the local 
system's epoch */ 


/* 
* Get a thread-local buffer to hold the returned 
* time. 
W/ 
struct tm *tmPtr = 
{struct tm *)Tcl_GetThreadData ( 
&tmKey, (int) sizeof(struct tm)); 


#ifdef HAVE_LOCALTIME R 
localtime_r(timePtr, tmPtr); 
#else 
Tcl_MutexLock (&clockMutex) ; 
memcpy ((VOID *) tmPtr, (VOID *) localtime 
(timePtr), sizeof(struct tm)); 
Tcl_MutexUnlock (&clockMutex) ; 
#endif 
return tmPtr; 
} 


The storage space is allocated by 1c1_cetrnreaapata and then filled in by either 
the iccaitime r function or the regular iccaitime function while protected by a 
mutex. 
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47. Building Tcl and Extensions 


This chapter discusses how to compile Tcl, Tcl extensions, and code that 
embeds Tcl on three platforms: Unix (including Linux and the various BSD 
systems), Mac OS, and Windows. For most people, compiling Tcl is not 
really necessary, as there are various ways to get binary distributions, as 
discussed in Appendix A. However, if you are integrating Tcl into your own 
program, you need to be familiar with the process. Building extensions to 
load in Tcl is often the best approach, and this chapter explains how to go 
about doing so in a portable way. 


47.1 Building Tcl and Tk 


The source code for Tcl and Tk is maintained on SourceForge, whose main 
project home page is at nttp://tcl.sourceforge.net. Tel and Tk are maintained 
as separate projects on the site. You can download released versions of the 
source code from the file distribution links, or you can access the CVS 
repositories via anonymous access as described on the site. Released 
versions of the sources are also available from 
http://www. tcl.tk/software/tcltk/download.ntm. If you check out the source via 
CVS, you end up with top-level source directories named tci and tx. In 
contrast, if you download a specific released version of the source, the top- 
level directories have the version number appended to their names, such as 
EGLS'.525% 
Each source distribution has a rzanme file in its top-level directory with 
general information and references to additional information about Tcl. 
There is also a set of subdirectories, including 

* aoc/—Tcl/Tk reference documentation 

® generic/—Source code applicable to all supported platforms 

* 1iprary/—a library of Tcl scripts used by Tcl/Tk 

* macosx/—-Macintosh-specific source code, make files, and Xcode 

project files 

* tests/—the Tcl/Tk test suite 

* tools/—tools used when generating Tcl distributions 

* unix/——Unix-specific source code, configure, and make files 

* win/—Windows-specific source code and make files for use with 
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Microsoft Visual C++ 
Each significant subdirectory includes its own rzanve file describing its 
contents. The zzanme files for the macosx, unix, and windows directories also 
provide up-to-date information for building Tcl or Tk for those platforms. 
You should always consult these reap files to check for any new 
dependencies, system requirements, or build procedures. 


47.1.1 Building Tcl and Tk on Unix 


Building Tcl on Unix is fairly straightforward. Tcl uses GNU Autoconf to 
handle system build dependencies. Therefore, you can configure, build, and 
install Tcl or Tk using the typical procedure: 


# cd to tcel/unix or tk/unix 
./configure 

make 

make install 


Note 


Before doing the make install, you can optionally run maxe test to run the 
Tcl or Tk test suite to verify the build on your system. Be aware that the 
test suite might take considerable time to execute. 


You can provide standard options to configure, SUCH aS --prefix to specify the 
installation directory and --exec-prerix to specify the installation directory for 
architecture-specific files. The --prerix option is especially handy for 
installing multiple versions of Tcl on a single system or building one or 
more personal Tcl/Tk installations for testing purposes without interfering 
with the system version of Tcl/Tk. The default prefix on Unix systems is 
/usr/local, although Tcl is also often installed (for example, on Linux) in /usr. 
See the Autoconf documentation for more information on standard configure 
options (ntt»://www.gnu.org/software/autocont 1§ One online resource). 
Additionally, Tcl and Tk provide some package-specific options to configure 
that affect how they are compiled. Most of them follow the standard syntax 
of enabling or disabling a feature using the --enabie-reature and --disable- 
feature Options. The more significant ones include 


--enable-shared 
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Compile as a shared library if enabled (the default), otherwise as a static 
library. 

® --enable-threads 
Compile with multithreading support if enabled; the default is disabled. 
(Many precompiled distributions of Tcl now enable this feature.) 

® --enable-64bit 
Enable 64-bit support (where applicable); the default is disabled. 

® --enable-symbols 
Compile with debugging symbols if enabled; the default is disabled. 


© --with-tcl=location 


(Tk only) Specifies the directory where Tcl was built. By default, the Tk 
build system assumes that this directory is ../../tci<version>, Where <version> 
is the same version of Tk being built. If this is not the case, you must specify 
the appropriate directory with --witn-tc1 to build Tk successfully. 

Among other things produced while building Tel is a file called tcicontig.sn, 
which is used by the Tcl Extension Architecture (described in Section 47.2) 
to hold information about the Tcl installation for use with extension 
compilation. It is a shell script that defines a number of variables such as 
the Tcl version; the C compiler used to compile Tcl; compiler and linker 
flags; the location of include files, libraries, and paths; and so on. Building 
Tk creates an analogous file, txconfig. sh. 


47.1.2 Building Tcl and Tk on Mac OS 


Building Tcl on the Macintosh requires at least Mac OS X 10.1; earlier 
versions are no longer supported. (Tcl/Tk 8.4 was the last version that had 
support for the “classic” Mac OS series.) You must also have Apple’s 
Developer Tools installed on your system. 
One option for building Tcl/Tk on the Macintosh is to use the Umx build 
system found in tci/unix and tx/unix. In that case, you follow the exact same 
steps as described in Section 47.1.1. There are a few additional configure 
options that apply only to builds on Mac OS: 

® --enable-corefoundation 
Use Apple’s Core Foundation framework; enabled by default. 


® --enable-framework 


Package shared libraries in Mac OS X frameworks; disabled by default. 


--enable-aqua 
(Tk only) Use the Aqua windowing system, rather than X11; disabled by 
default. Requires Tcl and Tk to be built with the Core Foundation 
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framework. 

Alternatively, the tci/macos and tx/macos directories contain a cnumakefiie that 
you can use to build and install Tcl and Tk directly. The following steps are 
sufficient for a standard installation. They assume that your Tcl and Tk 
source directories are contained within a common parent, and for generality, 
they’re presented assuming that a shell variable name ver exists containing 
the version string (e.g., 8.5.5) for a specific released version, or an empty 
string if you are building from CVS. First, to actually build the packages, 
you would open a terminal, go to the common parent directory, and execute 


make -C tcl${ver}/macosx 
make -C tk${ver}/macosx 


Then, to install the package onto your system’s root volume (which requires 
the administrator password): 


sudo make -C tcl${ver}/macosx install 
sudo make -C tk${ver}/macosx install 


To install into an alternate location, such as your home directory (for 
example, if you don’t have administrator privileges, or if you want to test 
against multiple versions of Tcl): 


make -C tcl${ver}/macosx install INSTALL ROOT="${HOME}/" 
make -C tk${ver}/macosx install INSTALL ROOT="${HOME}/" 


Other maxe targets and options are available. Consult the xzanm= file for more 
information. 

Finally, the macosx subdirectories also contain several project files that you 
can use with different versions of Apple’s Xcode integrated development 
environment. Once again, see the rzanve file for information on which project 
file to use and how the files are configured. 


47.1.3 Building Tcl and Tk on Windows 


There are several options for building Tcl/Tk on Windows, depending on 
what tools you have installed. 

If you have Microsoft Visual C+-+, the tc1/win and tx/win directories contain a 
makefile.ve file that you can use with nmaxe. Each file contains comments 
describing the targets and options available. The ¢c1/win directory contains a 
Microsoft Developer Studio workspace and project file that you can use as 
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well. 

Alternatively, you can use the open-source MinGW and MSYS tools to 
build Tcl on Windows. (See netp://www.mingw.org to read more about and to 
download these tools.) These tools provide a “Minimalist GNU for 
Windows,” including standard GNU compilers and build utilities. For this 
option, tci/win and tx/win include configure Scripts that you can use to follow 
the same sequence Of configure, make, ANd make install aS for Unix. If you 
choose this approach, you can use the same set of configure options as 
described in Section 47.1.1. 


47.2 The Tcl Extension Architecture (TEA) 


If you are writing your own extension in C, you could use any build system 
you like to compile the extension for use, write your own make files, and so 
on. However, if you plan to distribute your extension for use on a variety of 
platforms, it’s very difficult to design a general system to handle all of your 
target platforms. 

Tcl has a standard system for building extensions called TEA, which stands 
for “Tcl Extension Architecture.” TEA is based on the GNU Autoconf tool 
and provides a system for building extensions. TEA also defines best 
practice policies for extension development and distribution. 

The starting point for using TEA for your extensions is a sample extension 
designed to illustrate the TEA system and to serve as a template for 
extension development. The sample extension is maintained on SourceForge 
as part of the Tcl project (nttp://tci.sourceforge.net). You can obtain it from 
the CVS repositories via anonymous access as described on the site. The 
module name 1S sampicextension. 


Note 


The sample extension also contains a subdirectory named tea, which 
contains more detailed documentation on TEA as well as guidelines 
for developing portable extensions. As TEA continues to evolve, this 
is likely to be the most up-to-date documentation on TEA. 


The heart of TEA is Autoconf and the configure script that it generates. 
Autoconf takes two template files, configure.in and makefile.in, along with a 


840 


set of M4 macro definitions, supplied in a file named aciocai.ma, and 
generates an appropriate configure script that people can use to build your 
extension. The sample extension ships with commented, general-purpose 
configure. in and Makefile.in files that you can adapt for use by your extension, 
as well as a set of M4 macros to include in your aciocai.m4 that implement the 
TEA build infrastructure. In practice, if you start with the files from the 
sample extension, all you need to do is edit the configure.in and Makefile.in 
files, then execute autocone in the directory containing your extension to 
generate your extension’s configure script. 


Note 


In addition to the sample extension, TEA assumes that you have 
development tools installed on your system, including Autoconf. To use 
Autoconf to create a configure script on a Windows development 
system, you must have the open-source MinGW and MSYS tools 
installed as well as Autoconf. (See nttp://www.mingw.orqg to read more 
about and to download these tools.) 


Autoconf is required only for your development system so that you can 
create the configure Script for your extension. Users of your extension, who 
would build it on their own systems, require only appropriate development 
tools to be installed. They can then use the configure script you provide to 
actually build the extension on their systems. 

After the configure script has been run, your extension should be ready to 
build, which you can do by issuing the maxe command. Installation is handled 
by make install. Other targets include make test, 1f you have defined tests and 
provided a way to run them, and the extremely useful make aist, which 
bundles your source and configure files into a distribution (by default, a 
gzipped tar file) that is ready to ship. 


47.2.1 TEA Standard Configure Options 


TEA defines a large set of options for the configure script it generates, which 
users of your extension can use to configure your extension when they build 
it on their systems. Most of them follow the standard syntax of enabling or 
disabling a feature using the --cnabie-feature aNd --disable-feature Options. The 
more significant ones include 
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® --enable-shared 


Compile as a shared library if enabled (the default), otherwise as a static 
library. 

® --enable-threads 
Compile with multithreading support if enabled (the default). 


© --enable-64bit 


Enable 64-bit support (where applicable); the default is disabled. 


--enable-symbols 
Compile with debugging symbols if enabled; the default is disabled. 

® --with-tcl=location 
Specifies the directory where Tcl was built. This allows you to build your 
extension for multiple versions of Tcl or for multiple platforms. If you don’t 
have multiple versions of Tcl installed on your system, Autoconf can often 
find this information automatically. 

® --with-tk=location 
Specifies the directory where Tk was built. This option might be required 
only if your extension uses the Tk C API. If you don’t have multiple versions 
of Tk installed on your system, Autoconf can often find this information 
automatically. 

® --with-tclinclude=location 
Specifies the directory where the Tcl include files can be found (most 
notably, tci.n). 

® --with-tcllib=location 
Specifies the directory where the Tcl libraries can be found (most notably, 
libtclstubs.a). 

© --prefix 
Defines the root of the installation directory. Defaults to the value given to 
Tcl when it was built. 

© --exec-prefix 


Defines the root of the installation directory for platform-specific files. 
Defaults to the value given to Tcl when it was built. 


47.2.2 Directory Layout for TEA Extensions 


TEA recommends a standard directory structure for organizing your 
extension’s source within a common parent directory: 

* demos/—demonstration scripts for the extension 

* doc/—extension reference documentation 

* generic/—Source code applicable to all supported platforms 
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* library/—Supporting scripts, such as default bindings for widgets 

* macosx/——-Macintosh-specific source code 

* tests/—the extension test suite 

* unix/—-Unix-specific source code 

* win/—Windows-specific source code 

Additionally, the sample extension provides the following files and 
directories in support of TEA: 

* tclconfig/—a directory containing tc1.m4, which defines a collection of 
Autoconf macros used by TEA, and instaii-sn, a program used for 
copying files to their installation locations 

* tea/—a directory containing documentation on the current version of 

TEA 

aclocal.ma—a file used by Autoconf as input when generating the final 
configure Script 

configure.in—the script template used by Autoconf to generate the 
final configure script 

® Makefile.in—the template used by configure to generate the final makerite 

® pkgIndex.tcl.in—the template used by configure to generate the final 
pkgIndex.tcl file 

The make instai1 command installs a TEA package relative to the --prerix and 
--exec-prefix directories. For example, for the compiled library files and 
pkgindex.tc1 file, the installer creates a subdirectory under the sprerix/1ip 
directory consisting of the package name concatenated with the package 
version number, such as threaa2.6.5. By default, files are installed to the 
following locations: 

®  sexec-prefix/lib/$packagesversion/—Compiled library files and the 
pkgIndex.tcl file 

® sexec-prefix/pin/—binary executables and dependent .ai files on 
Windows 

* sprefix/include/—C header files 

® sprefix/man/—-Umx man pages from the aoc source directory 


47.2.3 Customizing the aciocai.m File 


One input to Autoconf is the aciocai.ma file, located in the root of your source 
directory. This file defines the M4 macros used to process the configure. in 
file and produce the configure script. The sample extension provides the file 
tclconfig/tc1.m4 that defines all of the M4 macros needed for the TEA build 
system, so in most cases your aciocai.m4 file can contain just the following 
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line: 
builtin(include,tclconfig/tcl.m4) 


If you want to extend the configure script options for your extension or 
otherwise customize the build system, you can add more macro definitions 
to this file. 


47.2.4 Customizing the configure. in File 


The configure.in file 1s a template containing a series of M4 macros that 
determine how the resulting configure script behaves. The sample extension 
provides a well-annotated version of this file, and in most cases you can 
simply edit the file as needed in the sections marked for you to change. In 
general, the order of the macros is important; mixing them up can cause 
problems that are difficult to trace. 

The first macro in your configure.in file is ac mtr, which initializes the 
environment and specifies the name and version number of your extension: 


AC_INIT([tclifconfig], [0.1]) 


Next you initialize the TEA variables, specifying the version of TEA, and 
instruct Autoconf to use the tciconfig subdirectory for additional build 
scripts and definitions: 


TEA_INIT({3.7]) 
AC_CONFIG_AUX_DIR(tclconfig) 


The next two macros are responsible for finding and loading the tcicontig.sh 
file, which is created when you build Tcl. It contains information such as the 
Tcl version; the C compiler used to compile Tcl; compiler and linker flags; 
the location of include files, libraries, and paths; and so on. TEA 
incorporates heuristics to try to find a Tcl installation on the target system 
containing a tciconfig.sh file, but a person building your extension can also 
use the --witn-tc1 Option tO configure to identify a specific directory. This is 
especially useful when building your extension against multiple versions of 
Tcl or for multiple platforms. There are no arguments to provide to these 
macros: 


TEA PATH TCLCONFIG 
TEA_LOAD_TCLCONFIG 
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If your extension also uses the Tk C API, you need two macros to find and 
load an analogous txcontig.sn file created when Tk is built: 


#TEA PATH TKCONFIG 
#TEA LOAD TKCONFIG 


The next two macros are required to handle the --pretix argument and to 
identify the appropriate C compiler and its options: 


TEA_PREFIX 
TEA_SETUP_COMPILER 


The next set of macros is specific to your extension. Most important is a 
space-separated list of C source files to compile; you do not need to specify 
the subdirectory containing the file as long as it is one of the standard TEA 
source directories: 


TEA ADD SOURCES([sample.c tclsample.c]) 


If other extensions or applications would compile against your extension, 
you might need to provide a list of public header files that you want 
installed on the target system with the make instai11 command: 


TEA_ADD_HEADERS({]) 


If required, you can list additional libraries needed to compile the 
extension, additional directories containing required include files, and 
additional compiler flags: 


TEA_ADD_LIBS({]) 
TEA_ADD_INCLUDES([]) 
TEA_ADD_CFLAGS({]) 


You can also provide a list of additional Tcl source files that are part of 
your extension: 


TEA_ADD_TCL_SOURCES({]) 


In the next section, you can provide platform-specific configuration 
instructions. In the condition sections, you can include additional calls to the 
tra app * Macros to list platform-specific source files, dependent libraries, 
and so forth: 
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if test "${TEA_PLATFORM}" = "windows" ; then 
else 
fi 


Next you specify which Tcl and Tk headers your extension needs. At a 
minimum, you'll need the Tcl public header (tci.n). If you need to compile 
against the Tk C API, you'll also need the Tk public header (tx.n) and the 
macro for locating the X11 headers. If at all possible, you should avoid 
using the private headers because the data structures and API may change 
without notice, whereas the Tcl Core Team makes every effort to keep the 
exported public C API very stable: 


TEA_PUBLIC_TCL_ HEADERS 
#TEA_PRIVATE_TCL_HEADERS 
#TEA_PUBLIC_TK_ HEADERS 
#TEA_PRIVATE TK HEADERS 
#TEA PATH X 


The next set of macros does some standard processing during configuration 
—checking whether or not to compile with multithreaded support, to build 
shared or static libraries, to include symbols or not, and general compiler 
options: 


TEA_ENABLE_ THREADS 
TEA ENABLE SHARED 
TEA_CONFIG CFLAGS 
TEA ENABLE SYMBOLS 


Chapter 36 discussed the use of Tcl’s stubs mechanism, which allows an 
extension compiled against one version of Tcl to be used with later versions 
of Tcl. Extensions should almost always use stubs to be as independent as 
possible of Tcl versions. On the other hand, if you are compiling code that 
links to Tcl as a library, rather than creating an extension, you should not use 
stubs—they serve no purpose. Use the following declaration to enable stubs 
for the Tcl C API and, if needed, the Tk C API: 


AC_DEFINE(USE_TCL_STUBS) 
#AC_DEFINE(USE_TK STUBS) 


Next is a standard TEA macro that generates a command line to use when 
building a library: 
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TEA_MAKE LIB 


The following macros determine the names of the ¢tcish and/or wisn 
executables, which are used by the build system only to run test cases in 
response to the maxe test command: 


TEA PROG TCLSH 
#TEA_ PROG WISH 


The last line of the file lists all of the files that the conrigure script needs to 
create: 


AC_OUTPUT([Makefile pkgIndex.tcl]) 


Each file listed must have a template file in the same directory, named with 
a .in Suffix. At a minimum, you'll need maxefiie.in. You can also have 
Autoconf manage the creation of a pxgtndex.tci file, as illustrated by the 
sample extension. For a cross-platform extension, you might find it easier to 
maintain separate make files in the different source subdirectories, such as 
the following code that creates additional make files in the generic, unix, and 
win Subdirectories from the respective templates: 


AC_OUTPUT ( [ 
Makefile 
generic/Makefile 
unix/Makefile 
win/Makefile 


)) 


Some additional TEA macros are available which are not covered in this 
section, and you can also use standard Autoconf macros to manage aspects 
of the build process. See the TEA documentation that comes with the sample 
extension for more information on these features. 


47.2.5 Customizing the makefi1e.in File 


The maxefile.in file serves as a template for the maxeriie that is to be 
generated. Trying to create a makefile.in from scratch that you could use with 
TEA would be difficult and tedious. The recommended approach is to base 
your make file template on the makeriie.in that comes with the sample 
extension, which in most cases works “out of the box.” You might want to 
customize it to go beyond the basic build process, such as using it for 
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running tools to build your documentation in different formats on different 
platforms (e.g., Unix man pages versus Windows help files) or performing 
custom cleanup operations. The actual customization of the file is beyond 
the scope of this chapter. See the TEA documentation that comes with the 
sample extension for more information. 


47.2.6 Building an Extension on Windows 


TEA is based on Autotools, the GNU build system. The open-source 
MinGW and MSYS tools provide the environment necessary to build a TEA 
extension on a Windows system (see ntty://www.mingw.org). If you feel that 
your target users are willing to use MinGW and MSYS to build your 
extension on Windows, you can use the same configure Script as for Unix; 
Windows users would do the same sequence of configure, make, and make 
install to build your extension on their systems. 

If you prefer, you can decide to create and deliver a Visual C++ make file 
for your extension as well. The sample extension provides an example in 
win/makefile.vc. It has been designed to be as generic as possible but still 
requires some additional maintenance to synchronize with the TEA 
configure.in and makefile.in files. Instructions for using the Visual C++ make 
file are written in the first part of the makeriie.ve file. 


47.3 Building Embedded Tel 


When Tcl is embedded in other systems, it is probably necessary to integrate 
the Tcl build system with that of your program. If the program that embeds 
Tcl uses Autotools, it shouldn’t be too difficult to accomplish. The basic 
approach is to use the TEA macros by including the tc1.ma file, so that it’s 
possible to obtain information about how Tcl is compiled. 
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A. Installing Tcl and Tk 


The source code and reference documentation for Tcl and Tk are freely 
available. Tcl and Tk are available under a BSD-style license, which 
provides great flexibility, including the use of Tcl and Tk in commercial 
products without royalties or being required to open-source your own code. 
This appendix describes different methods for retrieving the Tcl and Tk 
distributions for use on your local system. 


A.1 Versions 


Tcl and Tk are distributed separately, and each distribution has a version 
number. A version number consists of two or more integers separated by a 
period, such as 8.5.3 or 8.4. The first of the numbers is the major version 
number and the second is the minor version number. A third number, if 
present, indicates a patch release, usually containing only bug fixes; it’s 
rare for a patch release to introduce any significant new functionality. Each 
new release of Tcl or Tk gets a new version number. If the release is 
compatible with the previous release, it is called a minor release: the minor 
version number increments and the major version number stays the same. 
For example, Tcl 8.5 was a minor release that followed Tcl 8.4. Minor 
releases are compatible in the sense that C code and Tcl scripts written for 
the old release should also work under the new release without 
modifications. If a new release includes incompatible changes, it is called a 
major release: the major version number increments and the minor version 
number resets to 0. For example, Tcl 8.0 was a major release that followed 
Tcl 7.6. When you upgrade to a major release, you will probably have to 
modify your scripts and C code to work with the new release. 

Although Tcl can be used by itself, each release of Tk is designed to be used 
with a particular release of Tcl. When it starts up, Tk checks the Tcl release 
number to be sure that it will work with Tk. The matching releases of Tcl 
and Tk don’t necessarily have the same version numbers; for example, Tk 
3.6 required Tcl 7.3. However, all modern Tcl and Tk releases since 8.0 
share version numbers to avoid confusion. 
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A.2 Bundled Tel Distributions 


Many Unix and Unix-like operating systems have precompiled Tcl/Tk 
distribution packages available. (Many have the Tcl and Tk source 
available as distribution packages as well.) Some operating systems include 
Tcl and Tk by default when you install the operating system or offer it as an 
option in a “developer” package. If Tcl and Tk are not available on your 
operating system’s installation media, or you want to upgrade to a newer 
version of Tcl/Tk, you should be able to find Tcl/Tk distribution packages 
from the official package repositories for your operating system. You can 
use whatever package management utilities are supported on your operating 
system (for example, rpm, yum, dpkg, apt-get, etc.) to handle installing, 
upgrading, and uninstalling Tcl/Tk on your system. 

One disadvantage to using such official Tcl/Tk distribution packages is that 
there can be a delay—sometimes substantial—between the release of a new 
version of Tcl/Tk and the availability of an official distribution of the new 
version for your operating system. It can also be more difficult to install 
multiple versions of Tcl/Tk for use on the same system, or to install and 
maintain Tcl/Tk for multiple platforms for use from a shared network file 
system. 


A.3 ActiveTcl 


ActiveState Software (nttp://www.activestate.com) 1§ a Company that creates 
development tools and provides service and support for several dynamic 
languages, including Tcl. In addition to their commercial products, 
ActiveState offers a free, precompiled version of Tcl called ActiveTcl, 
which also bundles several popular Tcl extensions. ActiveTcl is available 
for several platforms, including Windows, Linux, Mac OS X, Solaris, AIX, 
and HP-UX at this time. ActiveTcl is often the easiest way to install Tcl/Tk 
on your system if your focus is Tcl/Tk script development. 


A.4 Telkits 


Chapter 14 discussed the use of Tclkits as a strategy for distributing your 
Tcl/Tk-based applications. A Tclkit is a single-file executable containing the 
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entire Tcl distribution in a remarkably small footprint (typically well under 
2MB). You can use the Tclkit executable as a Tcl shell, just as you would 
tcish. Precompiled Tclkits are available for a variety of platforms. You can 
find out more about Telkits at ntto://www.equid.com/tcikit and 
http: //wiki.tel.tk/tclkit and download Telkits from 


http: //www.equi4.com/tclkit/download.html. 


A.5 Compiling Tel/Tk from Source Distributions 


The source code for Tcl and Tk is maintained on SourceForge, whose main 
project home page is at nttp://tcl.sourceforge.net. Tel and Tk are maintained 
as separate projects on the site. You can download released versions of the 
source code from the file distribution links, or you can access the CVS 
repositories via anonymous access as described on the site. Released 
versions of the sources are also available from 


http://www.tcl.tk/software/tcltk/download.html. Detailed instructions for 


compiling and installing Tcl and Tk are provided in Chapter 47. 
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B. Extensions and Applications 


Tcl/Tk has an active user community. Many people have built packages that 
extend the base functionality of Tcl and Tk and applications based on Tcl 
and Tk. Several of these packages and applications are publicly available 
and widely used in the Tcl/Tk community. There isn’t space in this book to 
discuss all of the available Tcl/Tk software in detail, but this appendix 
gives a quick overview of several extensions and applications. 


B.1 Obtaining and Installing Extensions 


The best source for information on available Tcl extensions and 
applications is the Tcler’s Wiki (ntto://wiki.tci.tx). There you can search for 
topics of interest and find links to related extensions and applications. The 
Wiki also contains a page listing Tcl/Tk extensions, http: //wiki.tcl.tk/940. 
Another excellent resource is the “Great Unified Tcl/Tk Extension 
Repository” maintained by Joe English, 
http://www. flight lab.com/~joe/qutter/browse.ntmi. Each provides links to where 
you can download the desired extensions. Authors also often announce new 
versions of extensions and applications on the comp.iang.tc1 Usenet 
newsgroup (see Section C.1). 


B.1.1 Installing Extensions Manually 


Once you have downloaded an extension, follow the instructions that 
accompany it for installing it on your system. Some extensions provide 
installer applications, and some you copy to an appropriate location where 
Tcl can find them on your system. A zzapve file should be included with the 
extension that tells how to install it and describes any peculiarities. 

If the extension provides no installation instructions, usually you can simply 
copy the extension to one of the directories where Tcl looks for extensions 
by default. If the extension is distributed as a Tcl module, you can copy the 
file to one of the directories described in Section 14.6.2. If the extension is 
distributed as a package with separate files, including a pxgtndex.tci file, you 
can move the directory containing the extension files to one of the 
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directories described in Section 14.5.4. 


B.1.2 Installing Extensions from ActiveState TEApot Repositories 


ActiveState (ntto://www.activestate.com) has developed a Tcl package 
management system that provides a simple method for obtaining, installing, 
and updating Tcl extensions and applications. It allows you to use a client 
application named teacup to browse, search, and install extensions from 
hosted repositories running a repository server application named teapot. 
ActiveState’s free ActiveTcl distribution includes the teacup application and 
documentation, but you can also download a copy of it for your platform 
from http://teapot.activestate.com. ActiveState hosts a public TEApot at 
http://teapot.activestate.com Containing a variety of extensions and 
applications. You can get help for teacup and its options by executing teacup 
nelp. Additionally, you can read more about teacup on the Tcler’s Wiki at 
hnttp://wiki.tcl.tk/teacup. The documentation included with ActiveTcl also 
describes the availability of teapot for establishing your own TEApot 
repositories (e.g., a company-hosted TEApot containing approved versions 
of open-source and proprietary extensions for internal use). 

The teacup application includes a set of subcommands for managing one or 
more local installation repositories that serve as a source of extensions for 
use by your Tcl installation. In other words, if you have installed a 
particular extension in one of your installation repositories, the Tcl shells 
configured to use the repositories can successfully load the extension with a 
package require Command. Most often you would use just one installation 
repository, known as the default installation repository. You can query or 
change the default repository directory with the teacup default Command: 


teacup default 
= /Library/Tel/teapot 


You can also create and delete additional repositories and configure your 
Tcl installations to use different sets of repositories. See the teacup 
documentation for more details. 

The teacup 1ist Command lists the extensions available from the TEApot. 
You can also provide a specific extension name and optionally a version of 
that extension. If there is not an exact match for the name, the command does 
a case-insensitive substring search for candidate names. To list extensions 
that you have installed in your default repository, include the --at-daefauit 
option; for example: 
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teacup list --at-default file 
>entity name version platform 


1 entity found 


You can get a description of an extension using the teacup describe Command. 
As with teacup 1ist, you can get descriptions either for extensions available 
on the TEApot or, with the --at-cerauit option, for installed extensions; for 
example: 


teacup describe Img 
=> Entity Img 


Description @ http://teapot.activestate.com 

The Img package provides support for several image formats 
beyond the standard formats in Tk (PBM, PPM, and GIF), 
including BMP, XBM, XPM, GIF (no LZW), PNG, JPEG, TIFF, 
and PostScript. 


The teacup insta11 command installs a named extension. You can optionally 
specify a minimum or exact version to install; by default the latest version 
available is installed. If the extension has dependencies on other extensions 
not already installed, teacup automatically installs them as well. You can use 
the --ary-run option to simulate the installation, in which case teacup install 
reports the steps it would take during the installation. 

To upgrade your installation repository, use the teacup upaate command. By 
default, this updates all installed extensions and applications to the latest 
version available in the TEApot and installs any uninstalled extensions and 
applications from the TEApot. You can use the --oniy newer option to upgrade 
only currently installed extensions, or the --only uninstaliea option to install 
extensions and applications you don’t have installed already. The --ary-run 
option is also available to simulate the update process. 

The teacup remove command uninstalls a named extension or application. If 
you invoke it without naming an extension or application, it removes all 
items from the installation repository. The --ary-run option for simulating 
removal is also available for this command. 

You can use the teacup version Command to determine what version of teacup 1S 
installed. To upgrade to the latest version of teacup, execute teacup upgrade- 


self. 


Note 
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If you want to use teacup with a Tcl distribution other than ActiveTcl, 
you can download a copy of it for your platform from 
http://teapot.activestate.com You then need to set up an installation 
repository if you don’t already have one, set up your Tcl shell to be 
able to use repositories, and then link your shell to the repository you 
created. You can accomplish this with the following set of commands: 


teacup create /path/to/your/repository 
teacup setup /path/to/your/shell 
teacup link make /path/to/your/repository /path/to/your/shell 


B.2 TkCon Extended Console 


TkCon is an enhanced console for interacting with Tcl. Although the wisn 
interpreter has a bare-bones console, TkCon extends this basic functionality 
with many useful facilities to aid Tcl programming, including 

* Interactive command editing 

¢ A cross-session persistent command history 

¢ Enhanced history searching 

¢ Command, variable, and path expansion 

¢ Electric character matching (similar to emacs) 

* Command and variable highlighting 

¢ Capture of input, output, error, or command history to log files 

¢ “Hot errors,” where clicking on an error result displays a stack trace 

* Interactive debugging features 

¢ Extensive configuration options 
TkCon, developed by Jeff Hobbs, is written entirely in Tcl/Tk and can be 
embedded into a Tcl/Tk application to provide console support for the 
application. For more information, see the TkCon SourceForge page 
(nttp://tkcon.sourceforge.net) and the TkCon page on the Tcler’s Wiki 


(net 7 /wiks tol, tk/tkcon). 


B.3 The Standard Tel Library, Tellib 


Tcllib, otherwise known as the Standard Tcl Library, contains several 
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independent packages providing a variety of commonly used features, 
including 
¢ Networking protocol implementations, including e-mail (POP3 and 
SMTP), domain name resolution (DNS), file transfer (FTP), 
directory (LDAP), Usenet news (NNTP), chat (IRC), and network 
time (NTP) 
¢ Web support for parsing and generating HTML, generating 
JavaScript, writing CGI scripts, and working with URLs and MIME 
attachments 
¢ Encryption and checksum support for CRC checksums, DES, MD4, 
MDS, SHA1, and base64 encoding 
¢ Programming utilities for logging, profiling performance, and 
generating documentation 
¢ Data structure implementations, including stacks, queues, matrixes, 
graphs, and trees 
¢ The Snit object-oriented framework 
¢ Text-processing utilities, including CSV processing 
¢ Advanced math functions 
For more information, see the ‘Tecllib SourceForge page 
(http: //tcllib.sourceforge.net) and the Tcllib page on the Tcler’s Wiki 


(http: //wiki.tel.tk/tcllib). 


B.4 Additional Image Formats with Img 


Img is a Tk extension that adds support for many image formats beyond the 
small number supported natively by Tk. Img includes support for formats 
including BMP, GIF, ICO, JPEG, Pixmap, PNG, PPM, PostScript, SGI, Sun, 
TGA, TIFF, XBM, and XPM. The Img extension comes from Jan Nijtmans. 
For more information, see the Img page on the Tcler’s Wiki 
(http: //wiki.tcl.tk/imq) and the Img SourceForge page 


(net ://sourceforge.net/projects/tkim ). 


B.5 Sound Support with Snack 


The Snack sound extension adds commands to play and record audio. Snack 
supports in-memory sound objects, file-based audio, and streaming audio, 
with background audio processing. It handles file formats such as AIFF, AU, 
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MP3, NIST/Sphere, and WAV. Snack is courtesy of Kare Sjélander. You can 
find out more about Snack at the Snack home page 
(ntt ://www.s eech. kth.se/snack) and the Snack page on the Tcler’s Wiki 


(net =f fw ka bel, tk/snack). 


B.6 Object-Oriented Tel 


One of the historical criticisms of Tcl has been the lack of native object- 
oriented structures. However, this resulted in people developing several 
object-oriented extensions, each with its own unique features and strengths. 
[incr Tcl], also known as Itcl (the name is a play on the Tcl version of the 
C++ operator used to name C++), implements a framework very similar to 
C++. You can define classes consisting of data members and methods, with 
public, protected, and private protection levels available for each. 
Inheritance, including multiple inheritance, is supported. Additionally, you 
can use the object-oriented Tk widgets in the [incr Tk] and [incr Widgets] 
packages. [incr Tcl] was created by Michael McLennan. For more 
information, see the [incr Tcl] page on the Tcler’s Wiki (netp://wiki.tci.tk/62) 
and the [incr Tcl] SourceForge page (http: //inertcl. sourceforge .net/itcl). 
XOTcl, or extended object Tcl, extends an earlier object-oriented package 
called OTcl. XOTcl provides a number of object-oriented concepts to help 
reduce the complexity of large-scale programs. These concepts include mix- 
in classes, nested classes, aggregations, forwarders to support delegation, 
slots for storing data, and filters that provide features similar to aspect- 
oriented programming. XOTcl comes from Uwe Zdun and Gustaf Neumann. 
For more on XOTcl, see the XOTcl home page (http://www. xotcl.org) and the 
XOTcl page on the Tcler’s Wiki (nttp://wiki.tecl.tk/xotcl). 

Snit, short for Snit’s Not Incr Tcl, provides an alternative object-oriented 
extension written in pure Tcl. Unlike most object-oriented languages or 
language extensions, Snit is based on delegation, not inheritance. Snit 
objects delegate work to child components, rather than inherit from base 
classes. While it used to be a separate extension, Snit is now part of Tcllib, 
described in Section B.3. Snit was developed by William Duquette. For 
more on Snit, see the Snit page on the Tcler’s Wiki (nttp://wiki.tcl.tk/3963) 


and the Snit reference page (http: //tcllib : sourceforge .net/doc/snit.html). 


Note 
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Tel 8.6 will introduce a native object-oriented framework. Although it 
will be sufficient for stand-alone use in scripts, its primary purpose is 
to serve as a core for other object-oriented extensions, making them 
easier to implement and more efficient. 


B.7 Multithreaded Tel Scripting 


Chapter 47 discussed the requirements for embedding Tcl in a multithreaded 
application and described the functions in Tcl’s C API that support 
platform-neutral, multithreaded development. Tcl does not have any built-in 
commands that expose multithreading at the script level. The Thread 
extension—originally written by Brent Welch and now maintained by Zoran 
Vasiljevic—provides a set of script-level commands for creating and 
managing threads in an application. 

The Thread extension supports what is often called an apartment threading 
model. Each thread created at the script level has its own Tcl interpreter, 
which maintains its own variables, procedures, namespaces, and other state 
information. The Thread extension also implements a message-passing 
mechanism for inter-thread communication, shared variables, mutual 
exclusions (mutexes), condition variables, and thread pools. 

You can use the Thread extension only in a tcisn, wisn, or other application 
that has been compiled with multithreaded support enabled, as described in 
Chapter 46. Also, any other binary extensions used by your application must 
be compiled with multithreaded support enabled as well. 

The source code for the Thread extension is maintained as a project on the 
Tcl SourceForge site: nttp://tcl.sourceforge.net. YOU can read more about the 
Thread extension on the Tcler’s Wiki, at bit: //wiki.tcl.tk/thread. 


B.8 XML Programming 


XML programming has become more important over the years, as XML has 
become a common serialization and data exchange format. Tcl has several 
extensions related to XML processing. 

Tc LXML groups a number of extensions related to parsing XML documents. 
The base extension, TclIXML, handles parsing XML documents. TclIDOM 
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adds a document object model, a way to manipulate XML as a tree structure 
in memory. TclXSLT adds XSL transformations, and TclTidy cleans up XML 
and HTML and is particularly useful for parsing HTML from web pages, 
many of which do not truly conform to HTML standards. TclIXML was 
created by Steve Ball. For more information, see the TcLXML SourceForge 
page (nttp://tclxml.sourceforge.net) and the TclXML page on the Tcler’s Wiki 
(http: //wiki.tel.tk/tclxml). 

tDOM provides an alternative for processing XML documents, including 
XSLT support. It is known for its processing speed and low memory 
consumption. The tDOM project was started by Jochen Loewer and is 
currently maintained by Rolf Ade. You can find out more about it at the 
tDOM home page (http://www.tdom.org) and the tDOM page on the Tcler’s 
Wiki (nttp://wiki.tel.tk/tclxml). 

TclSOAP helps you create XML messages for SOA, or service-oriented 
architectures, using the Simple Object Access Protocol, or SOAP. With 
SOAP, applications send and receive XML messages; the major advantage 
is that you can write programs in any language, such as Tcl, and not worry 
about the implementation of the program on the other side. TcISOAP was 
created by Pat Thoyts. For more information, see the TcISOAP SourceForge 
page (nttp://tclsoap.sourceforge.net) and the TclISOAP page on the Teler’s 
Wiki (net ://wiki.tcl.tk/tclsoa ). 


B.9 Database Programming 


Although Tcl doesn’t support database access natively, you can add a 
number of extensions to help access data from relational databases. 

Oratcl allows Tcl applications to access Oracle databases 
(nttp://oratcl.sourceforge.net). Mysqltcl similarly provides an interface to 
MySQL databases (nttp://www.xdobry.de/mysaitc1). PostgreSQL has the pgtcl 
extension for database access (http: //pafoundry.org/projects/patc1). Sybtcl 
provides Sybase support (nttp://syptci.sourceforge.net). The sqlite2 extension 
provides access to SQLite (htto://ww.saiite.org), TclLODBC allows Tcl 
applications to call on ODBC database drivers, most commonly used on 
Windows (ntt ://sourceforge.net/projects tclodbe). 


Note 
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Tcl 8.6 will introduce TDBC, an extension shipped as part of the Tcl 
core, to provide a standard interface for SQL database access. For 
more information, see the TDBC page on the Tecler’s Wiki 


(http: //wiki.tel.tk/tdbc). 


Another popular option is Metakit, which is designed to be an efficient 
embedded database library with a small footprint. The Mk4tcl extension 
provides a Tcl API for accessing Metakit. See nttp://www.equid.com/metakit for 
more information. 


B.10 Integrating Tcl and Java 


The Tcl/Java Project provides two routes for integrating Tcl and Java code. 
One option is TclBlend, an extension that supports loading a Java interpreter 
into an existing Tcl process. As a result, you can use Tcl script commands to 
load Java classes, create objects, invoke methods, and so forth. The other 
option is Jacl, a self-contained implementation of a Tcl interpreter written 
entirely in Java. The intent of Jacl is to incorporate scripting functionality 
into an existing Java application. You can find out more at the Tcl/Java 
home page (http: //tcliava.sourceforge.net) and the Tcl/Java page on the Tcler’s 
Wiki (nttp://wiki.tel.tk/tcljava). 


B.11 SWIG 


If you have an existing library of C/C++ code, you might want to make its 
functionality available through Tcl script commands. Although you could 
write your own wrapper code to expose the various functions as Tcl 
commands, a tool called SWIG can create the wrapper code for you 
automatically. SWIG is not limited to use with just Tcl but can also generate 
wrapper code for many other dynamic languages. See the SWIG home page 
(nttp://www.swig.org) for more information. 


B.12 Expect 


Expect is one of the oldest Tcl applications and also one of the most 
popular. It is a program that “talks” to interactive programs. An Expect 
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script describes what output can be expected from a program and what the 
correct responses should be. It can be used to automatically control 
programs such as ftp, teinet, ssh, fsck, and others that cannot be automated 
from a shell script because they require interactive input. Expect also 
allows the user to take control and interact directly with the program when 
desired. For example, the following Expect script logs into a remote 
machine using the ssn program, sets the working directory to that of the 
originating machine, then turns control over to the user: 


package require Expect 
spawn ssh [lindex Sargv 0] 
expect -nocase "password:" 
send [lindex Sargv 1] 
expect -re "(%|#) " 

send "cd [pwd] \r" 

expect -re "(%|#) " 
interact 


The spawn, expect, send, and interact Commands are implemented by Expect, but 
lindex and pwa are built-in Tcl commands. The spawn command starts up ssn, 
using a command-line argument as the name of the remote machine (iindex 
extracts the first argument from the command line, which is available in the 
variable argv). The expect command waits for ssn to output a password 
prompt, matching it in a case-insensitive manner. The script assumes that the 
password is the second command-line argument and sends it to the ssn 
program. (This approach is insecure and shown for simplicity only. There 
are several other approaches for handling password prompts like this in 
Expect that are beyond the scope of this section.) The script waits for a 
shell prompt (either « or +, followed by a space), then sena outputs a 
command to change the working directory, just as if a user had typed the 
command interactively. The following expect command waits for a prompt 
signifying that the -a command has been processed. Finally, interact Causes 
Expect to step out of the way so that the user who invoked the Expect script 
can now type directly to ssn. 

Expect can be used for many purposes, such as acting as a scriptable front 
end to debuggers, mailers, and other command-line-driven programs that 
don’t have scripting languages of their own. The programs require no 
changes to be driven by Expect. Expect is also useful for regression testing 
of interactive programs. Expect can be combined with Tk or other Tcl 
extensions. For example, by using Tk and Expect together, it 1s possible to 
write a graphical front end for an existing interactive application without 
changing the application. 
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Expect was created by Don Libes of the National Institute of Standards and 
Technology. For more information, see the Expect home page 
(nttp://expect.nist.gov) and the Expect page on the Tcler’s Wiki 


(net ://wiki.tcl.tk/ex ect). 


B.13 Extended Tel 


Extended Tcl (TclX) is a library package that augments the built-in Tcl 
commands with many additional commands and procedures oriented toward 
system programming tasks. Here are a few of the most popular features of 
TelX: 
* Access to many additional POSIX system calls and functions such as 
fork and kill 
° A file-scanning facility with functionality much like that of the awx 
program 
* Keyed lists, which provide functionality similar to C structures 
* Facilities for debugging, profiling, and program development 
Many of the best features of TclX are no longer part of it: they turned out to 
be so widely useful that they were incorporated into the Tcl core. Among the 
Tcl features pioneered by TclX are file input and output, TCP/IP socket 
access, array variables, real arithmetic and transcendental functions, 
autoloading, and the incr and upvar commands. 
Extended Tcl was created by Karl Lehenbauer and Mark Diekhans. For 
more information, see the TclX SourceForge page (http: //tclx. sourceforge net) 
and the TclX page on the Tcler’s Wiki (ntto://wiki.tcl.tk/telx). 
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C. Tcl Resources 


The following are suggested resources for more information on Tcl/Tk. 


C.1 Online Resources 


Several online resources are available for Tcl/Tk, including 

* Tcl Developer’s Xchange, nttp://www. tcl. tk 
A good contact point for keeping up to date with the Tcl world. The Tel 
Developer’s Xchange announces new Tcl releases, upcoming conferences, 
and other significant Tcl events. It also hosts online versions of the Tcl/Tk 
reference documentation for current and historical releases, Tcl download 
links, and Tcl advocacy information. 

© Tcler’s Wiki, nttp: //wiki.tel.tk 
A collaboratively edited collection of Tcl wisdom, tips, and code samples. 
This site is a treasure trove of Tcl information and should be the first place 
to check when researching Tel topics. 

° uae Programmer Network (ASPN) Tcl Resources, 


ht aspn.activestate.com/ASPN/Tcl 


Astivesune s ASPN provides information on technologies supported by 
ActiveState, including Tcl. The site hosts several Tcl-related mailing lists, a 
Tcl “cookbook,” and other resources. From this site you can also freely 
download ActiveTcl, ActiveState’s binary build of Tcl, and several popular 
Tcl extensions. 

: TkDocs, http: //www.tkdocs.com 
Mark Roseman’s site providing Tk tutorials and documentation. Mark has 
some excellent tips for cross-platform Tk development, and his tutorials 
cover Tk not only for Tcl but for other dynamic languages like Perl and 
Python as well. 

¢ Tcl SourceForge Project, nttp://tcl.sourceforge.net 
The source code repository for Tcl/Tk and core extensions. 

¢ The comp.iang.tc1 Usenet newsgroup 
The Usenet newsgroup for the exchange of information about Tcl/Tk and 
related extensions and applications. The newsgroup is used to answer 
questions from Tcl/Tk users, to exchange information about bugs and their 
fixes, and to discuss possible new features in Tcl and Tk. New releases of 
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Tcl/Tk also are announced on this newsgroup, as are releases of other 
related extensions and applications. You can access the Usenet newsgroups 
through dedicated news client applications or through web gateways such as 
Google Groups (http: //groups..google.com). 
¢ The Tcl chatroom 

A real-time chat service for discussing Tcl/Tk, currently based on the XMPP 
protocol. Many experienced Tcl programmers are regular contributors, 
readily answering questions, solving problems, and debating Tcl/Tk 
development. The chatroom can be accessed via standard XMPP clients, a 
dedicated TkChat client (nttp://txchat.tci.tk), and web and IRC gateways. 
See http: //wiki.tcl.tk/1i7g On the Tcler’s Wiki for the latest information on 
how to access the Tcl chatroom. 


C.2 Books 


Several books are available for more information on Tcl/Tk and related 
topics: 
¢ Butenhof, David R. Programming with POSIX Threads. Reading, 
MA: Addison-Wesley, 1997. 
¢ Flynt, Clif. 7cl/Tk: A Developers Guide, Second Edition. San 
Francisco: Morgan Kaufmann, 2003. 
¢ Friedl, Jeffrey. Mastering Regular Expressions, Third Edition. 
Sebastopol, CA: O’Reilly Media, Inc., 2006. 
¢ Libes, Don. Exploring Expect: A Tcl-based Toolkit for Automating 
Interactive Programs. Sebastopol, CA: O’ Reilly Media, Inc., 1994. 
¢ Welch, Brent, and Ken Jones. Practical Programming in Tcl and Tk, 
Fourth Edition. Upper Saddle River, NJ: Prentice Hall, 2003. 
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